Integração com GitHub Actions

Q: npm audit falha em dependência transitiva que não podemos corrigir?

Documente a exceção em docs/security-audit-exceptions.md com data de expiração. Não desabilite permanentemente o audit na CI.

Um guia de receitas para GitHub Actions + proteção de branch em equipes Node.js - verificações obrigatórias, releases baseadas em tags e templates de PR que capturam lacunas de migração e rollback antes do merge.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# .github/workflows/pr-checks.yml
name: PR Checks
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm test -- --ci
      - run: npm audit --audit-level=high

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*"]
 
jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm test -- --ci
      # docker build + push para o registry

<!-- .github/pull_request_template.md -->
## Resumo
 
## Ticket
<!-- API-___ -->
 
## Checklist de API / DB
- [ ] OpenAPI ou lista de rotas atualizada
- [ ] Migração incluída (ou N/A)
- [ ] Plano de rollback documentado
- [ ] Compatibilidade do worker verificada (se o esquema de eventos mudou)
 
## CI
- [ ] Verificação `quality` verde localmente: `npm ci && npm run typecheck && npm test`

Proteção de branch (UI do GitHub):

Exigir verificação de status: quality
Exigir revisões de PR: 1
Exigir histórico linear ou merge squash (escolha da equipe)
Não permitir bypass para main

Quando usar isso:

Primeiro repositório backend migrando de "confie em mim, eu rodei os testes" para portões de qualidade impostos
Desvios de lockfile causando falhas apenas em CI
Deployments de produção sem tag precisam de rastreabilidade semver
Monorepo precisa de filtros de caminho para pular serviços não relacionados

Exemplo de Trabalho

Passo 1 - Combinar scripts locais e de CI

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint src test",
    "test": "node --import tsx --test test/**/*.test.ts",
    "build": "tsc -p tsconfig.build.json"
  }
}

# .husky/pre-push
npm run typecheck && npm test

Passo 2 - Filtro de caminho para monorepo

on:
  pull_request:
    paths:
      - "services/orders-api/**"
      - "package-lock.json"
 
defaults:
  run:
    working-directory: services/orders-api

Passo 3 - Gate de migração (job opcional)

  db-lint:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run db:migrate
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test

Passo 4 - Verificações obrigatórias na proteção de branch

Settings → Branches → main → Require status checks:
  ✓ quality
  ✓ db-lint (se migrações no PR)

Labels de PR (Opcional)

Label	Efeito
`skip-audit`	Apenas Docs; auditoria dispensada com aprovação de segurança
`has-migration`	Dispara o job db-lint
`worker-change`	Exige nota de deploy do worker no template

FAQs

npm audit falha em dependência transitiva que não podemos corrigir?

Documente a exceção em docs/security-audit-exceptions.md com data de expiração. Não desabilite permanentemente o audit na CI.

Matriz Node 20 e 24 durante a atualização?

Matriz temporária nas verificações de PR durante a migração LTS. Remova a versão N-2 quando a frota estiver totalmente na 24.18.0.

Quem pode enviar tags?

Restrinja a criação de tags para gerentes de release ou bot de CI. Tags disparam produção - proteja com regras.

Relacionados

Fundamentos de Git para Equipes Node - branches e tags
Melhores Práticas de Git & GitHub - resumo portátil
GitHub Actions para Node - matriz e artefatos
Melhores Práticas de Gerenciadores de Pacotes - política de npm ci

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.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# .github/workflows/pr-checks.yml
name: PR Checks
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm test -- --ci
      - run: npm audit --audit-level=high

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*"]
 
jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm test -- --ci
      # docker build + push para o registry

<!-- .github/pull_request_template.md -->
## Resumo
 
## Ticket
<!-- API-___ -->
 
## Checklist de API / DB
- [ ] OpenAPI ou lista de rotas atualizada
- [ ] Migração incluída (ou N/A)
- [ ] Plano de rollback documentado
- [ ] Compatibilidade do worker verificada (se o esquema de eventos mudou)
 
## CI
- [ ] Verificação `quality` verde localmente: `npm ci && npm run typecheck && npm test`

Proteção de branch (UI do GitHub):

Exigir verificação de status: quality
Exigir revisões de PR: 1
Exigir histórico linear ou merge squash (escolha da equipe)
Não permitir bypass para main

Quando usar isso:

Primeiro repositório backend migrando de "confie em mim, eu rodei os testes" para portões de qualidade impostos
Desvios de lockfile causando falhas apenas em CI
Deployments de produção sem tag precisam de rastreabilidade semver
Monorepo precisa de filtros de caminho para pular serviços não relacionados

Exemplo de Trabalho

Passo 1 - Combinar scripts locais e de CI

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint src test",
    "test": "node --import tsx --test test/**/*.test.ts",
    "build": "tsc -p tsconfig.build.json"
  }
}

# .husky/pre-push
npm run typecheck && npm test

Passo 2 - Filtro de caminho para monorepo

on:
  pull_request:
    paths:
      - "services/orders-api/**"
      - "package-lock.json"
 
defaults:
  run:
    working-directory: services/orders-api

Passo 3 - Gate de migração (job opcional)

  db-lint:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run db:migrate
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test

Passo 4 - Verificações obrigatórias na proteção de branch

Settings → Branches → main → Require status checks:
  ✓ quality
  ✓ db-lint (se migrações no PR)

Labels de PR (Opcional)

Label	Efeito
`skip-audit`	Apenas Docs; auditoria dispensada com aprovação de segurança
`has-migration`	Dispara o job db-lint
`worker-change`	Exige nota de deploy do worker no template

FAQs

npm audit falha em dependência transitiva que não podemos corrigir?

Documente a exceção em docs/security-audit-exceptions.md com data de expiração. Não desabilite permanentemente o audit na CI.

Matriz Node 20 e 24 durante a atualização?

Matriz temporária nas verificações de PR durante a migração LTS. Remova a versão N-2 quando a frota estiver totalmente na 24.18.0.

Quem pode enviar tags?

Restrinja a criação de tags para gerentes de release ou bot de CI. Tags disparam produção - proteja com regras.

Relacionados

Fundamentos de Git para Equipes Node - branches e tags
Melhores Práticas de Git & GitHub - resumo portátil
GitHub Actions para Node - matriz e artefatos
Melhores Práticas de Gerenciadores de Pacotes - política de npm ci

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.

Integração com GitHub Actions

Buscar na documentação

Integração com GitHub Actions