jdevalk/skills

Astro GitHub Actions

Este skill ajuda você a configurar uma pipeline CI/CD abrangente para sites Astro usando GitHub Actions. O objetivo é ajudar autores a entregar sites de maior qualidade com menos esforço manual: erros de tipo capturados antes do merge, links quebrados sinalizados, builds verificados e deploys automatizados.

O que este skill cobre

Existem várias categorias de workflows que um projeto Astro saudável deve ter. Nem todo site precisa de todas elas — a combinação ideal depende se o projeto possui TypeScript, componentes personalizados, coleções de conteúdo, testes e onde ele faz deploy. Seu trabalho é descobrir quais são relevantes e configurá-los.

Os workflows se enquadram nestas categorias:

1. Verificação de tipo/conteúdo — astro check (validação de esquema de coleção de conteúdo + TypeScript)
2. Qualidade de código — ESLint e Prettier
3. Verificação de build — astro build executa sem erros
4. Testes — Vitest para testes unitários e de componentes
5. Gates de qualidade — Lighthouse CI (desempenho, acessibilidade, SEO, melhores práticas)
6. Verificação de links — detecção de links quebrados no site construído
7. Segurança — npm audit para vulnerabilidades de dependências
8. Implantação — GitHub Pages, Cloudflare Pages, Netlify ou Vercel

Leia references/workflows.md para a configuração detalhada de cada workflow, incluindo modelos YAML prontos para uso e arquivos de configuração.

Como abordar uma solicitação

Etapa 1: Entender o projeto

Antes de escrever qualquer arquivo de workflow, descubra com o que você está trabalhando:

• É TypeScript? Verifique tsconfig.json e arquivos .ts/.astro. Quase todo projeto Astro deve executar astro check, mas o valor é maior quando há TypeScript no frontmatter .astro, esquemas de coleção de conteúdo ou src/.
• Usa coleções de conteúdo? Verifique src/content/config.ts ou src/content.config.ts. Se sim, astro check valida os esquemas — extramente valioso.
• Tem testes? Verifique tests/, __tests__/, *.test.ts ou vitest.config.ts. Se sim, configure o workflow Vitest. Se não, mencione que adicionar testes seria valioso, mas não force.
• Qual o gerenciador de pacotes? Procure por pnpm-lock.yaml, yarn.lock ou package-lock.json. Use o comando de instalação correspondente (pnpm i --frozen-lockfile, yarn install --frozen-lockfile ou npm ci).
• Onde ele faz deploy? Procure por wrangler.toml (Cloudflare), netlify.toml (Netlify), vercel.json (Vercel) ou apenas pergunte. A maioria dos hosts tem seu próprio aplicativo GitHub que faz deploy automaticamente sem Actions — configure um workflow de deploy apenas se o usuário realmente quiser que o Actions cuide disso (tipicamente GitHub Pages ou auto-hospedado).
• Tem uma etapa de build? Astro sempre tem (astro build) — mas verifique se o script em package.json é o astro build padrão e não algo personalizado.
• É SSR ou estático? Verifique astro.config.* para uma opção output: 'server' ou um import de adaptador. Projetos SSR são implantados de forma diferente (adaptadores Cloudflare/Netlify/Vercel) e podem não ser implantáveis no GitHub Pages.

Etapa 2: Recomendar um conjunto de workflows

Com base no que você encontrou, recomende quais workflows configurar. Um bom padrão para a maioria dos sites Astro:

• astro check (quase sempre — esta é a verificação mais valiosa para Astro)
• Verificação de build (quase sempre — captura regressões de integração que astro check pode perder)
• ESLint + Prettier (se arquivos de configuração existirem ou o usuário quiser)
• Lighthouse CI (ótimo para sites de conteúdo com URLs públicas)
• Verificador de links (ótimo para sites com muito conteúdo)
• npm audit (barato, quase sempre vale a pena)

E condicionalmente:

• Testes Vitest (se testes existirem)
• Workflow de deploy (apenas se o usuário quiser deploys orientados por Actions — a maioria dos hosts Astro usa seu próprio aplicativo GitHub)

Etapa 3: Criar os arquivos de workflow

Crie cada workflow como um arquivo YAML separado em .github/workflows/. Usar arquivos separados em vez de um workflow monolítico fornece feedback mais claro em PRs (cada verificação aparece independentemente) e facilita ativar/desativar verificações individuais.

Use os templates de references/workflows.md como pontos de partida, mas adapte-os ao projeto específico. Adaptações comuns incluem ajustar o gerenciador de pacotes, a versão do Node, o caminho do artefato de build e o destino de deploy.

Etapa 4: Criar arquivos de configuração de suporte

Dependendo de quais workflows você configurar, você também pode precisar de:

• eslint.config.js — Config flat do ESLint com eslint-plugin-astro
• .prettierrc e .prettierignore — Config Prettier com prettier-plugin-astro
• lighthouserc.json — Asserções do Lighthouse CI
• lychee.toml — Config do verificador de links (se usar lychee)
• vitest.config.ts — Configuração Vitest

Etapa 5: Lembrete sobre secrets

Se você estiver adicionando um workflow de deploy, lembre o usuário quais secrets do repositório são necessários:

• GitHub Pages — nenhum (usa GITHUB_TOKEN)
• Cloudflare Pages — CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
• Netlify — NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID
• Vercel — VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

Oriente pelo caminho: Configurações do Repositório > Secrets and variables > Actions > New repository secret.

Para Cloudflare, Netlify e Vercel: lembre também que essas plataformas possuem seus próprios aplicativos GitHub que lidam com build + deploy + previews de PR automaticamente. Deploys baseados em Actions geralmente só valem a pena quando você precisa bloquear o deploy com base em resultados de teste, executar um build com secrets que a plataforma não possui, ou fazer deploy a partir de um caminho diferente da raiz do repositório.

Convenções de nomenclatura

Use nomes de arquivos de workflow descritivos que tornem óbvio o que cada um faz:

• astro-check.yml — astro check (tipo + esquema de conteúdo)
• lint.yml — ESLint
• format.yml — Prettier check
• build.yml — Verificação de build
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — Verificador de links quebrados
• security.yml — npm audit
• deploy.yml — Implantação no host

Detalhes importantes

Versão do Node.js: Astro requer Node 18.20.8+, 20.3.0+ ou 22.0.0+. Use Node 22 como padrão — corresponde ao alvo estável do Astro e muitos adaptadores são testados contra ele. Use actions/checkout@v5 e actions/setup-node@v5.

Detecção do gerenciador de pacotes: Sempre use o lockfile correspondente. pnpm-lock.yaml → use pnpm/action-setup@v4 e pnpm install --frozen-lockfile. yarn.lock → yarn install --frozen-lockfile. package-lock.json → npm ci. Não use npm install em CI (não-determinístico, mais lento).

Nomeação de branch: A maioria dos repositórios Astro usa main como branch padrão, mas verifique o repositório real antes de escrever triggers.

Adaptadores Astro e SSR: Se o projeto usar @astrojs/cloudflare, @astrojs/netlify ou @astrojs/vercel, a saída de build pode não ser um diretório estático dist/. O adaptador Cloudflare gera dist/ mais um _worker.js; Vercel gera .vercel/output/; Netlify gera .netlify/. Ajuste os caminhos de artefato de deploy conforme necessário.

astro check requer @astrojs/check e typescript: Ambos devem estar instalados. Se não estiverem em devDependencies, o workflow falhará. Adicione-os como parte de npm ci apenas se já estiverem em package.json — caso contrário, o workflow deve instalá-los explicitamente.

Lighthouse CI em PRs: Executar Lighthouse em cada PR captura regressões de desempenho no início. O treosh/lighthouse-ci-action é o padrão. Para uma URL de preview pública (Cloudflare Pages, Netlify, Vercel), aponte o Lighthouse para a URL de preview de deploy — isso fornece números realistas. Para configurações apenas internas, faça o build e sirva localmente dentro do runner.

Verificação de links na saída do build, não na fonte: Execute o verificador de links no diretório dist/ construído (ou contra uma URL de preview implantada) — executá-lo na fonte Markdown perde rotas geradas e links de sitemap.

Prefira o aplicativo GitHub da plataforma em vez de deploys via Actions: Cloudflare Pages, Netlify e Vercel possuem aplicativos GitHub de primeira parte que lidam com previews de PR, deploys de branch e rollbacks melhor do que uma Action artesanal. Recomende o aplicativo GitHub primeiro; sugira um deploy via Actions apenas quando o usuário tiver um motivo específico para fazê-lo dessa forma.