Noções Básicas de CI/CD

Q: CI em main após o merge?

Sim. Reexecute os gates em main para capturar desvios de merge. Algumas equipes confiam apenas em PR; reexecutar em main é mais seguro.

Q: Estratégia de Monorepo?

Filtros de caminho: paths: ['services/api/'] disparam apenas workflows afetados. Use Turborepo ou Nx para detecção de afetados.

Q: Como os deploys do Lambda se encaixam?

CI constrói o artefato zip; CD executa aws lambda update-function-code com o mesmo objeto S3 nomeado por SHA.

10 exemplos para estruturar CI (validação de pull request) e CD (deploy de release) para serviços Node.js 24 TypeScript - 7 básicos e 3 intermediários.

Pré-requisitos

mkdir node-service && cd node-service
npm init -y
npm pkg set type=module
npm install express@5
npm install -D typescript@5.6 vitest eslint @types/node

Para detalhes específicos do GitHub Actions, consulte GitHub Actions para Node e Quality Gates.

Exemplos Básicos

1. Estágios do Pipeline de PR

PR aberto / push
  -> install (npm ci)
  -> lint
  -> typecheck
  -> unit test
  -> (opcional) integration test
  -> bloquear merge se qualquer etapa falhar

O pipeline de PR prova que o commit é seguro para merge
Nenhum deploy no pipeline de PR para a maioria das equipes (ambientes de preview são opcionais)
Feedback rápido: alvo de menos de 10 minutos para estágios de unidade

2. Estágios do Pipeline de Release

Tag / merge para main
  -> install + test (repetir gates)
  -> build (tsc / docker build)
  -> scan image / audit
  -> push artifact (registry / S3 zip)
  -> deploy staging
  -> smoke test staging
  -> deploy production (aprovação manual ou progressiva)

O pipeline de release produz o artefato implantável
Mesmo SHA git de teste para produção
Veja Melhores Práticas de CI/CD

3. Scripts de CI no `package.json`

{
  "scripts": {
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "build": "tsc -p tsconfig.json",
    "audit:ci": "npm audit --audit-level=high"
  }
}

CI chama scripts npm, não comandos de ferramentas brutos espalhados no YAML
tsc --noEmit captura erros de tipo sem emitir arquivos
Fixar versões de ferramentas em package.json devDependencies

4. Fluxo de Trabalho Mínimo de PR no GitHub Actions

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test

cache: npm acelera as instalações quando o lockfile não muda
Executa em pull_request e push para main
Veja GitHub Actions para Node

5. Ordem de Falha Rápida

steps:
  - run: npm ci
  - run: npm run lint      # segundos
  - run: npm run typecheck # segundos
  - run: npm run test      # minutos
  - run: npm run build     # após os testes passarem

Coloque as verificações mais baratas primeiro
Não construa Docker antes que os testes de unidade passem
Jobs paralelos para lint vs teste se o repositório for grande

6. Separação de Ambientes

Ambiente	Gatilho	Propósito
`ci`	Cada PR	Apenas validação
`staging`	Merge para `main`	Integração pré-produção
`production`	Tag ou workflow aprovado	Tráfego do cliente

Staging usa configuração semelhante à de produção com dados anonimizados
O deploy de produção requer aprovação ou canary - Canary e Entrega Progressiva

7. Imutabilidade de Artefatos

- name: Build and push image
  run: |
    IMAGE=ghcr.io/acme/api:${{ github.sha }}
    docker build -t "$IMAGE" .
    docker push "$IMAGE"

Marque imagens com github.sha, não apenas :latest
Implante staging e prod com o mesmo digest
Rollback = reimplantar SHA anterior

Exemplos Intermediários

8. Workflow Reutilizável

# .github/workflows/reusable-node-ci.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"
 
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npm run lint && npm run typecheck && npm run test

# .github/workflows/ci.yml
jobs:
  call-ci:
    uses: ./.github/workflows/reusable-node-ci.yml

DRY em monorepo de microsserviços
Cada workflow de serviço passa seu diretório de trabalho, se necessário

9. Workflow de Release com Proteção de Ambiente

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*.*.*"]
 
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test && npm run build
      - run: ./scripts/deploy.sh staging ${{ github.sha }}
 
  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: ./scripts/deploy.sh production ${{ github.sha }}

O environment do GitHub adiciona revisores necessários para produção
Staging deve passar antes que o job de produção comece

10. Gate de Commits Convencionais

- name: Validate commit messages on PR
  uses: wagoid/commitlint-github-action@v6

Habilita semver automatizado via Semantic Release
Impõe no pipeline de PR, não apenas no momento do release

FAQs

Os pipelines de PR devem implantar em algum lugar?

Ambientes de preview opcionais por PR - Preview Environments. Padrão: apenas validação, deploy no merge.

CI em main após o merge?

Sim. Reexecute os gates em main para capturar desvios de merge. Algumas equipes confiam apenas em PR; reexecutar em main é mais seguro.

Onde o build do Docker se encaixa?

Pipeline de release após os testes, ou pipeline de PR apenas para alterações no Dockerfile com gate de scan. Nunca pule os testes antes do push da imagem.

Estratégia de Monorepo?

Filtros de caminho: paths: ['services/api/**'] disparam apenas workflows afetados. Use Turborepo ou Nx para detecção de afetados.

Como os deploys do Lambda se encaixam?

CI constrói o artefato zip; CD executa aws lambda update-function-code com o mesmo objeto S3 nomeado por SHA.

E os segredos no CI?

Segredos do GitHub Actions e OIDC para AWS. Sem chaves AWS de longa duração no repositório. Veja Gerenciadores de Segredos.

Relacionados

GitHub Actions para Node - matriz e cache
Quality Gates - lint, audit, cobertura
Semantic Release - versionamento automatizado
Preview Environments - deploys de PR
CI/CD Best Practices - 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.

Pré-requisitos

mkdir node-service && cd node-service
npm init -y
npm pkg set type=module
npm install express@5
npm install -D typescript@5.6 vitest eslint @types/node

Para detalhes específicos do GitHub Actions, consulte GitHub Actions para Node e Quality Gates.

Exemplos Básicos

1. Estágios do Pipeline de PR

PR aberto / push
  -> install (npm ci)
  -> lint
  -> typecheck
  -> unit test
  -> (opcional) integration test
  -> bloquear merge se qualquer etapa falhar

O pipeline de PR prova que o commit é seguro para merge
Nenhum deploy no pipeline de PR para a maioria das equipes (ambientes de preview são opcionais)
Feedback rápido: alvo de menos de 10 minutos para estágios de unidade

2. Estágios do Pipeline de Release

Tag / merge para main
  -> install + test (repetir gates)
  -> build (tsc / docker build)
  -> scan image / audit
  -> push artifact (registry / S3 zip)
  -> deploy staging
  -> smoke test staging
  -> deploy production (aprovação manual ou progressiva)

O pipeline de release produz o artefato implantável
Mesmo SHA git de teste para produção
Veja Melhores Práticas de CI/CD

3. Scripts de CI no `package.json`

{
  "scripts": {
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "build": "tsc -p tsconfig.json",
    "audit:ci": "npm audit --audit-level=high"
  }
}

CI chama scripts npm, não comandos de ferramentas brutos espalhados no YAML
tsc --noEmit captura erros de tipo sem emitir arquivos
Fixar versões de ferramentas em package.json devDependencies

4. Fluxo de Trabalho Mínimo de PR no GitHub Actions

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test

cache: npm acelera as instalações quando o lockfile não muda
Executa em pull_request e push para main
Veja GitHub Actions para Node

5. Ordem de Falha Rápida

steps:
  - run: npm ci
  - run: npm run lint      # segundos
  - run: npm run typecheck # segundos
  - run: npm run test      # minutos
  - run: npm run build     # após os testes passarem

Coloque as verificações mais baratas primeiro
Não construa Docker antes que os testes de unidade passem
Jobs paralelos para lint vs teste se o repositório for grande

6. Separação de Ambientes

Ambiente	Gatilho	Propósito
`ci`	Cada PR	Apenas validação
`staging`	Merge para `main`	Integração pré-produção
`production`	Tag ou workflow aprovado	Tráfego do cliente

Staging usa configuração semelhante à de produção com dados anonimizados
O deploy de produção requer aprovação ou canary - Canary e Entrega Progressiva

7. Imutabilidade de Artefatos

- name: Build and push image
  run: |
    IMAGE=ghcr.io/acme/api:${{ github.sha }}
    docker build -t "$IMAGE" .
    docker push "$IMAGE"

Marque imagens com github.sha, não apenas :latest
Implante staging e prod com o mesmo digest
Rollback = reimplantar SHA anterior

Exemplos Intermediários

8. Workflow Reutilizável

# .github/workflows/reusable-node-ci.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"
 
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npm run lint && npm run typecheck && npm run test

# .github/workflows/ci.yml
jobs:
  call-ci:
    uses: ./.github/workflows/reusable-node-ci.yml

DRY em monorepo de microsserviços
Cada workflow de serviço passa seu diretório de trabalho, se necessário

9. Workflow de Release com Proteção de Ambiente

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*.*.*"]
 
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test && npm run build
      - run: ./scripts/deploy.sh staging ${{ github.sha }}
 
  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: ./scripts/deploy.sh production ${{ github.sha }}

O environment do GitHub adiciona revisores necessários para produção
Staging deve passar antes que o job de produção comece

10. Gate de Commits Convencionais

- name: Validate commit messages on PR
  uses: wagoid/commitlint-github-action@v6

Habilita semver automatizado via Semantic Release
Impõe no pipeline de PR, não apenas no momento do release

FAQs

Os pipelines de PR devem implantar em algum lugar?

Ambientes de preview opcionais por PR - Preview Environments. Padrão: apenas validação, deploy no merge.

CI em main após o merge?

Sim. Reexecute os gates em main para capturar desvios de merge. Algumas equipes confiam apenas em PR; reexecutar em main é mais seguro.

Onde o build do Docker se encaixa?

Pipeline de release após os testes, ou pipeline de PR apenas para alterações no Dockerfile com gate de scan. Nunca pule os testes antes do push da imagem.

Estratégia de Monorepo?

Filtros de caminho: paths: ['services/api/**'] disparam apenas workflows afetados. Use Turborepo ou Nx para detecção de afetados.

Como os deploys do Lambda se encaixam?

CI constrói o artefato zip; CD executa aws lambda update-function-code com o mesmo objeto S3 nomeado por SHA.

E os segredos no CI?

Segredos do GitHub Actions e OIDC para AWS. Sem chaves AWS de longa duração no repositório. Veja Gerenciadores de Segredos.

Relacionados

GitHub Actions para Node - matriz e cache
Quality Gates - lint, audit, cobertura
Semantic Release - versionamento automatizado
Preview Environments - deploys de PR
CI/CD Best Practices - 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.

Noções Básicas de CI/CD

Buscar na documentação

Noções Básicas de CI/CD