GitHub Actions para Node
Configure o GitHub Actions para serviços TypeScript do Node.js 24: builds em matriz, cache npm, artefatos e deploy OIDC.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
name: CI
on: [pull_request, push]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [22, 24]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm run lint && npm run typecheck && npm run testQuando usar isso: Todo repositório Node no GitHub. Este é o esqueleto padrão de CI antes dos jobs de Docker e deploy.
Exemplo Funcional
# .github/workflows/ci.yml
name: CI
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
quality:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
node-version: [22, 24]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
cache-dependency-path: package-lock.json
- name: Install
run: npm ci
- name: Lint
run: npm run lint
- name: Typecheck
run: npm run typecheck
- name: Test with coverage
run: npm run test -- --coverage
- name: Upload coverage
if: matrix.node-version == 24
uses: actions/upload-artifact@v4
with:
name: coverage
path: coverage/
retention-days: 7
docker:
needs: quality
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: |
ghcr.io/acme/api:${{ github.sha }}
ghcr.io/acme/api:main
cache-from: type=gha
cache-to: type=gha,mode=maxO que isso demonstra:
- Matriz Node 22 e 24 para compatibilidade LTS
cache: npmcom chave no lockfile viasetup-nodeconcurrencycancela execuções de PR superadas- Build Docker apenas em push para
mainapós a passagem do job de qualidade - Cache GHA do BuildKit para camadas de imagem mais rápidas
Mergulho Profundo
Comportamento do Cache npm
actions/setup-node@v4 com cache: npm faz o hash do package-lock.json. Para monorepos:
cache-dependency-path: |
package-lock.json
services/api/package-lock.jsonArtefatos vs. Cache
| Recurso | Usar para |
|---|---|
actions/cache | node_modules, camadas Docker |
actions/upload-artifact | Relatórios de cobertura, dist/ compilado, zips Lambda |
- uses: actions/upload-artifact@v4
with:
name: lambda-zip
path: function.zipO job de deploy downstream baixa o mesmo zip testado em CI.
OIDC para AWS (Sem Chaves Estáticas)
permissions:
id-token: write
contents: read
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
aws-region: us-east-1A política de confiança na role IAM limita a repo:acme/api:ref:refs/heads/main.
Contêineres de Serviço para Testes de Integração
services:
postgres:
image: postgres:16
env:
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 5s
--health-timeout 3s
--health-retries 5
steps:
- run: npm run test:integration
env:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgresArmadilhas
npm installem vez denpm ci- CI não reproduzível. Correção: comite o lockfile; sempre usenpm ci.- Matriz sem
fail-fast: false- Falha no Node 22 oculta o resultado do Node 24. Correção: definafail-fast: falseao comparar versões. - Cache manual de
node_modules- Frequentemente mais lento que o cache dosetup-node. Correção: use o cache npm integrado, a menos que a ferramenta do monorepo exija caminhos personalizados. - Tags
:latestde deploy apenas - Não é possível reverter. Correção: sempre envie a tag${{ github.sha }}. concurrencyausente - Pushes de PR enfileirados desperdiçam minutos. Correção: cancele execuções em andamento no mesmo branch.- Docker em todo PR sem filtro de caminho - Lento e caro. Correção:
paths: ['Dockerfile', 'src/**']ou construa apenas nomain.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| GitHub Actions | Repositório no GitHub | Organização apenas GitLab (use GitLab CI) |
| CircleCI / Buildkite | Runners personalizados, monorepos grandes | Repositórios de serviço único simples |
| Nx Cloud / Turborepo | Grafo de tarefas afetadas | Pequenos aplicativos de pacote único |
| Runners auto-hospedados | Testes de GPU ou internos à VPC | Repositórios públicos OSS padrão |
FAQs
Devemos usar matriz para Node 20, 22 e 24?
Matriz 22 e 24 se você suporta ambas as linhas Active LTS. Remova 20 quando for oficialmente descontinuado para seu produto.
Cache pnpm ou yarn?
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
cache: pnpmQuanto tempo a CI deve levar?
Menos de 10 minutos para estágios de unidade. Divida testes de integração lentos em um workflow noturno, se necessário.
Um workflow pode fazer CI e CD?
Possível, mas workflows separados melhoram a clareza: ci.yml em PR, release.yml em tag. Veja Noções Básicas de CI/CD.
Como executamos o Playwright?
Use o passo npx playwright install --with-deps e divida os testes entre jobs da matriz para suítes grandes.
Verificação de segredos?
Habilite a verificação de segredos do GitHub e a ação gitleaks em PRs. Bloqueie commits com conteúdo .env.
Relacionados
- Noções Básicas de CI/CD - pipelines de PR vs. release
- Portões de Qualidade - verificações necessárias
- Ambientes de Preview - workflows de deploy de PR
- Melhores Práticas de Docker - build de imagem em CI
- Melhores Práticas de CI/CD - checklist da seção
Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.