03-04, CI/CD

1. Problema de Engenharia

CI/CD é onde projetos perdem mais tempo do que admitem. Pipelines de 30 min em projetos pequenos. Builds que falham flaky aleatoriamente. Deploy manual disfarçado de "automated" porque alguém precisa apertar botão. Rollback que demora 20 min. Secrets em logs. Branches sem proteção. Devs que esperam CI verde e empurram outra vez sem entender o que falhou.

Este módulo é CI/CD profissional: pipeline rápido (paralelizado, cached), deploys reprodutíveis, rollback em segundos, segurança (supply chain, secrets), padrões modernos (trunk-based, GitFlow, deploy strategies, feature flags). Você sai com pipeline que confia.

2. Teoria Hard

2.1 CI vs CD

• Continuous Integration: código integra em mainline frequente, com testes automated rodando.
• Continuous Delivery: cada commit verde é deployable a qualquer momento (mas deploy é manual).
• Continuous Deployment: cada commit verde é automatically deployed em prod.

Continuous Deployment exige maturidade alta: testes confiáveis, observability forte, rollback automático, feature flags. Em projetos novos, comece em Continuous Delivery (deploy automático em staging, manual em prod) e suba.

2.2 Plataformas

• GitHub Actions: tightly integrado ao GitHub. Marketplace gigante. Default da maioria dos projetos novos.
• GitLab CI/CD: integrado ao GitLab, runners flexíveis.
• CircleCI, Buildkite, Drone: alternativas com strengths.
• Jenkins: clássico, ainda pesa em enterprise.
• Argo Workflows / Tekton: K8s-native.

Em 2026, GitHub Actions domina nos projetos open-source e médios. GitLab forte em enterprise self-hosted.

2.3 Pipeline anatomy

Estrutura típica:

PR opened → install → lint → typecheck → unit → integration → build → e2e → deploy preview
PR merge   → install → lint → typecheck → unit → integration → build → e2e → deploy staging → smoke → deploy prod (gated) → notify

Ou separado por workflows.

Princípios:

• Fail fast: lint antes de testes; cheap antes de caro.
• Paralelizar quando independente.
• Cache deps, build, Playwright browsers, Docker layers.
• Steps idempotentes.
• Determinístico: mesmo input = mesmo output.

2.4 Caching

• Lockfiles (pnpm, yarn) → cache de node_modules ou ~/.pnpm.
• Build artifacts (.next/cache, dist/).
• Test runners (Vitest cache, Playwright browsers download).
• Docker layers (docker/build-push-action com cache-from/cache-to em GHCR ou registry).

GitHub Actions:

- uses: actions/cache@v4
  with:
    path: ~/.pnpm-store
    key: pnpm-${{ hashFiles('pnpm-lock.yaml') }}

Restore parcial é problema sutil. Use restore-keys com prefix.

2.5 Matrix builds

Rodar mesma suite em múltiplas combinações:

strategy:
  matrix:
    node: [20, 22]
    os: [ubuntu-latest, macos-latest]

Útil pra libs cross-platform/cross-version. Em apps específicos a 1 stack, matrix é overhead.

2.6 Reusable workflows e composite actions

DRY pra pipelines com múltiplos repos ou múltiplos jobs similares:

• Composite action: pasta com action.yml, agrupa steps.
• Reusable workflow: arquivo .github/workflows/reusable.yml, called via uses:.

Em monorepo: 1 workflow base parametrizado, jobs por package.

2.7 Secrets management

• GitHub Secrets: encrypted, scoped (repo, env, org).
• Environment-specific (production, staging): exigem reviewer approval pra deploy.
• OIDC com cloud: melhor que long-lived secrets, runner trade GH OIDC token por AWS/GCP/Azure cred temporário. Sem chaves estáticas em GH.
• External secret stores: Vault, AWS Secrets Manager + External Secrets Operator (em K8s). Em CI, OIDC + secret manager.

Nunca logue secrets. CI mascara automaticamente, mas evite echo $SECRET.

2.8 Branch protection

GitHub Settings:

• Require PR review (1+ approvers).
• Require status checks (linha verde).
• Restrict pushes em main.
• Sign commits com GPG/sigstore.

Padrão: nada chega em main sem CI verde + revisão.

2.9 Branching strategies

• Trunk-based: feature flags + commit direto em main após review. Releases frequentes.
• GitHub Flow: branch curta → PR → merge em main → deploy. Simples. Padrão pra maioria.
• GitFlow: develop, release, hotfix branches. Pesado, projetos com release cadência longa.
• Release branches: cut N semanas, hotfix vira de volta. Apps mobile com release na store.

Em 2026, trunk-based + feature flags + deploys frequentes é dominante em SaaS. GitFlow ainda em projetos com binários distribuídos.

2.10 Versioning e changelog

• SemVer: MAJOR.MINOR.PATCH.
• CalVer: YYYY.MM.x. Pra apps com release contínuo.
• Conventional Commits (feat:, fix:, chore:): habilita auto-generation.
• changesets, semantic-release: bump version + changelog + tag automaticamente.

Pra serviços (não publicados como pkg), versioning ainda importa pra rastreabilidade, tag git por release.

2.11 Deploy strategies

• Recreate: down → up. Downtime.
• Rolling: gradual. Default em K8s. Sem downtime se readiness ok.
• Blue/Green: dois ambientes; switch traffic. Rollback instantâneo. Custo 2x.
• Canary: % de tráfego pra versão nova; aumenta se métricas ok.
• Shadow: tráfego espelhado pra versão nova sem afetar resposta.

Ferramentas: Argo Rollouts, Flagger (K8s). Manual via Service mesh weights ou Ingress canary annotations (Nginx).

2.12 Feature flags

• LaunchDarkly, Statsig, Unleash, GrowthBook, Flagsmith.
• Self-hosted (Unleash, GrowthBook) vs SaaS.
• Targeting por user, percent rollout, attribute-based.

Decoupling deploy de release. "Ship dark", ativa quando pronto. Reverter sem redeploy.

Cuidado com tech debt de flags antigas. Monitore staleness.

2.13 Build artifacts e registries

• Container images → registry (GHCR, ECR).
• Static sites → 04-03/CloudFront, Vercel, Netlify.
• npm packages → npm registry (público) ou GitHub Packages.
• Docs → GitHub Pages.

Imutabilidade: tag com SHA do commit. Promoção de staging pra prod deve usar mesma image, não rebuild.

2.14 Supply chain security

• Dependency scanning: Dependabot, Renovate.
• Image scanning: Trivy, Docker Scout, Snyk.
• SBOM (Software Bill of Materials): inventário de tudo que está na imagem. syft gera; CISA promove.
• Signing: cosign assina images; consumers verificam.
• SLSA (Supply-chain Levels for Software Artifacts): framework de níveis. SLSA 3+ exige reproducible builds e provenance.
• OIDC + keyless signing: cosign sem long-lived key.

Em 2026, supply chain virou regulado em algumas jurisdições. SBOM + signing é mainstream.

2.15 Monorepo CI

Monorepo (pnpm workspaces, Turborepo, Nx, Bazel) precisa skipar tarefas em packages não afetados:

• Turborepo: hashes de dependency graph; cacheia outputs por hash.
• Nx: similar com affected:* commands.
• Bazel: build system mais rigoroso, hermetic, sandbox.

Em CI: detectar mudanças por path (paths-filter) e disparar jobs só pros packages afetados.

Comparação real Turborepo vs Nx vs Bazel (2026)

Hermético (sandboxed): build em diretório isolado; só vê inputs declarados. Reprodutível bit-exato. Custa setup pesado e curva de aprendizado; ganho cresce com tamanho do repo.

Affected detection — 3 estratégias

1. Path-based (mais simples, menos preciso)

# .github/workflows/ci.yml
jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      site: ${{ steps.f.outputs.site }}
      api: ${{ steps.f.outputs.api }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - id: f
        uses: dorny/paths-filter@v3
        with:
          filters: |
            site:
              - 'apps/site/**'
              - 'packages/ui/**'      # dependência de site
            api:
              - 'apps/api/**'
              - 'packages/db/**'
  build-site:
    needs: detect
    if: needs.detect.outputs.site == 'true'
    runs-on: ubuntu-latest
    steps: [...]

Limite: você mantém manualmente o mapa "package depende de package". Erra quando refactor cross-package.

2. Affected via tool (Turbo/Nx) — preciso, automático

# Em PR contra main, calcula affected automaticamente do git diff
turbo run build --filter='[origin/main]'
turbo run test --filter='...{[origin/main]}'    # affected + downstream

# Nx equivalente
nx affected --target=build --base=origin/main
nx affected --target=test --base=origin/main

...{[origin/main]} (Turbo) ou affected --withRelated (Nx) inclui packages que dependem dos modificados — cobertura segura sem rodar tudo.

3. Bazel target-based — máxima precisão

# Lista alvos afetados pelo diff (bazel-diff tool)
bazel-diff get-impacted-targets-by-diff \
  --workspacePath . \
  --bazelPath $(which bazel) \
  --startingRevision $(git merge-base HEAD origin/main) \
  --finalRevision HEAD \
  --output impacted.txt

bazel test $(cat impacted.txt | xargs)

Custa setup bazel-diff + analysis caching; vence em monorepo de 100k+ targets.

Remote cache — onde os ganhos reais aparecem

Sem cache remoto, novo dev clona repo e roda pnpm build — 8min cold. Com cache remoto que outro dev populou, mesmo build pega artifacts já-buildados — 30s.

Turborepo Remote Cache (open spec):

# Self-hosted via Cloudflare Workers (gratis pra most teams)
# https://github.com/AdiRishi/turborepo-remote-cache-worker
echo "TURBO_API=https://your-worker.your-domain.workers.dev" >> .env
echo "TURBO_TEAM=mycompany" >> .env
echo "TURBO_TOKEN=$(openssl rand -hex 32)" >> .env

# Em CI:
turbo run build --remote-cache-timeout=10

Nx Cloud (paga; gratis tier limitado): ~$25-99/dev/mês; integra com Nx Console pra dashboards de cache hit rate.

Bazel BuildBuddy / EngFlow: SaaS ou self-host; remote build execution (RBE) também — workers em cluster K8s próprio, build paralelizado em N machines.

Padrão Logística monorepo

logistics-monorepo/
├── apps/
│   ├── site/                # Next.js público
│   ├── courier-app/         # Expo
│   └── api/                 # Fastify backend
├── packages/
│   ├── ui/                  # Design system shared
│   ├── db/                  # Drizzle schema + queries
│   ├── auth/                # auth client/server
│   └── tsconfig/            # tsconfig shared
├── turbo.json
└── pnpm-workspace.yaml

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env", "tsconfig.base.json"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "cache": true
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "lint": { "cache": true, "outputs": [] },
    "typecheck": { "dependsOn": ["^build"], "outputs": [] },
    "dev": { "cache": false, "persistent": true }
  }
}

CI workflow:

- run: pnpm install --frozen-lockfile
- run: turbo run lint typecheck test build --filter='...{[origin/main]}'
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: 'logistics'

Resultado em PR pequeno (packages/ui button styling): apenas ui + site + courier-app rebuildam; api cache hit. CI baixa de 12min pra 90s.

Caveats reais

• Cache hit rate é a métrica que importa: Datadog/Grafana dashboard de turbo run --output-logs=full | grep "cache hit". Abaixo de 70% em PR típico = cache config errada (input não declarado, env var vazando como input).
• Inputs implícitos quebram cache: variável de ambiente lendo process.env.X em build. Solução: declarar globalEnv: ["X"] em turbo.json ou injetar via --env-mode=strict.
• Cache poisoning: developer com node_modules corrompido publica artifact ruim em remote cache. Mitigação: cache key inclui lockfile hash; CI-only writes (devs só leem).
• Cross-platform cache (Linux CI vs macOS dev): hashes divergem em alguns setups (line endings, native binaries). Use dockerized builds em CI.

Cruza com 03-04 §2.4 (caching strategies em CI são fundamento), 02-04 (Next.js build é o consumidor mais frequente), 04-12 §2.10 (roadmap técnico inclui investment em build infra).

2.16 Observability do CI

Pipeline performance:

• Tempo total e por step.
• Flakiness rate (falha aleatória).
• Cache hit rate.
• Tempo de fila do runner.
• DORA metrics: deployment frequency, lead time, MTTR, change failure rate.

CI lento é dívida de produtividade. < 15 min ideal pra PR; < 5 min pro essencial.

DORA metrics, mensuração concreta no stack

Metrics canônicas (Forsgren, Humble, Kim — Accelerate, 2018) viraram industry standard. Mas a maioria mede errado ou não mede. Como mensurar em GitHub Actions + Railway (stack típico):

Implementação prática (GitHub Actions + Railway):

# .github/workflows/deploy.yml — adiciona timestamps em outputs
- name: Record deploy
  run: |
    gh api -X POST /repos/${{github.repository}}/dispatches \
      -f event_type=dora-deploy \
      -f client_payload='{"sha":"${{github.sha}}","timestamp":"${{ steps.deploy.outputs.completed_at }}"}'

Persistir em DB próprio (Postgres) ou stack de obs (Grafana com loki tags). Query SQL pra weekly report:

SELECT date_trunc('week', deploy_at) AS week,
       COUNT(*) AS deploys,
       PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY EXTRACT(EPOCH FROM (deploy_at - first_commit_at))) AS lead_time_p50_sec
FROM deploys WHERE branch='main' AND created_at > now() - interval '90 days'
GROUP BY 1 ORDER BY 1 DESC;

Categorias por performance (DORA 2024 State of DevOps Report):

Tools ready-made (zero implementação):

• LinearB: SaaS, integra GH/GitLab/Jira; calcula DORA + cycle time + WIP automaticamente.
• Sleuth: SaaS, integra com PR + deploy + incidents.
• Faros AI: open-source/SaaS. Cobre stack maior (Salesforce, etc).
• Allquiet, Apdex Cloud: alternativas leaner.
• DIY com Grafana + Postgres: 2-3 dias de trabalho, controle total. Vale se você já tem time de obs.

Anti-padrões a evitar:

• Otimizar deploy frequency separadamente — squad faz 30 deploys/dia, mas CFR é 40%. Trade-off entre velocity e estabilidade real.
• "Lead time = ticket idade no Jira". Errado. Lead time é code commit → prod, não product idea → prod (esse é cycle time, métrica diferente).
• Vanity metric: medir só pra dashboard bonito, nunca usar pra decisão. Se métrica não muda comportamento, descarte.

Cruza com 03-15 (incident management gera input pra MTTR), 04-12 (tech leadership usa DORA pra calibration de time).

2.17 Self-hosted runners

GitHub free runners (ubuntu-latest) limitados em concorrência e specs. Self-hosted:

• VMs próprias (EC2, fly machines).
• K8s com actions-runner-controller.
• BuildJet, Cirrus pra runners managed mais rápidos.

Self-hosted resolve cost em volume alto e specs específicas (GPUs, builds Mac iOS). Adiciona ops.

2.18 Pipeline pra mobile

iOS:

• macOS runner (caro).
• Provisioning, certs, code signing.
• TestFlight upload via fastlane ou EAS Submit.

Android:

• Linux ok.
• Keystore (secret), APK/AAB, Play Console upload.

EAS Build (Expo) terceriza tudo.

2.19 Release automation

• GoReleaser: pra binários (Go, Rust com plug-in).
• changesets: monorepo, pkg publish.
• Release Please (Google): conventional commits → release PR.
• semantic-release: full automation, opinionated.

2.20 Deployment strategies (blue/green, canary, progressive delivery, feature flags)

Strategy decision matrix:

Rolling deployment (K8s default)

kubectl set image deployment/api api=registry/api:v2 --record substitui pods gradualmente. Defaults: maxSurge: 25% + maxUnavailable: 25%. Em prod, force maxUnavailable: 0 (pod novo nasce ready antes de antigo morrer).

Pegadinha: readinessProbe mal calibrada → traffic vai pra pod sem app pronta. Implemente readiness lendo state real (DB connection, cache warmup, dependency health), não só GET / que responde 200 antes do app boot.

Rollback: kubectl rollout undo deployment/api (history default 10 revisions; tune via revisionHistoryLimit).

Blue/Green deployment

Dois ambientes completos (Blue current, Green new). LB faz switch instantâneo de todo traffic.

Pattern K8s: Deployments api-blue + api-green; Service selector version: blue → switch:

kubectl patch service api -p '{"spec":{"selector":{"version":"green"}}}'

Schema migration: backward-compat MANDATÓRIO. Add column nullable; dual-write durante cutover; drop em release N+2 (ver expand-migrate-contract abaixo). Custo: 2x infra durante cutover (minutos a horas). Trade-off aceitável pra zero-downtime + instant rollback.

Canary deployment

Deploy pra subset (5-10%) traffic. Monitora métricas. Aumenta gradualmente se healthy.

Argo Rollouts 1.7+ (controller K8s, OSS): canary declarativo:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata: { name: api-orders }
spec:
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: { duration: 5m }
        - analysis:
            templates: [{ templateName: success-rate }]
        - setWeight: 25
        - pause: { duration: 10m }
        - setWeight: 50
        - pause: { duration: 10m }
        - setWeight: 100

Alternativas: Flagger 1.36+ (Flux ecosystem). Service mesh integration: Istio VirtualService weights, Linkerd TrafficSplit. AnalysisTemplate consulta Prometheus (success rate, p99 latency, error budget burn).

Pegadinha: canary com 5% traffic em service low-traffic precisa rodar 30+min pra signal estatístico; em janela noturna o noise dominates.

Progressive delivery (canary + automated metrics gate)

Canary com auto-promote OU auto-rollback baseado em SLI metrics.

Promotion criteria típico: error rate < 0.5%, p99 latency increase < 20% vs baseline, Apdex > 0.95 sustentado 10min. Auto-rollback triggers: error rate spike, p99 > 2x baseline, alert externo (PagerDuty webhook).

Tooling 2026: Argo Rollouts + Prometheus + AnalysisTemplate; Flagger + Linkerd; Spinnaker (legacy enterprise, evite em greenfield).

Shadow / dark launch

Deploy v2 recebe traffic via mirror (tee), mas responses descartadas. Útil pra perf testing sob real load sem user impact. Istio: mirror: em VirtualService.

Use case: novo query plan Postgres; mirror real workload, compare latencies, zero risk. Nunca shadow em service com side effects (emails, payments) sem dry-run mode — duplicate effects em prod.

Feature flags em produção

Decoupling deploy de release: deploy code com flag OFF; turn ON gradualmente per cohort.

Tooling 2026:

• LaunchDarkly (managed, ~$20/seat/mês, enterprise standard).
• Unleash (OSS, self-host).
• Statsig (managed, A/B + flags + analytics integrated).
• OpenFeature (vendor-neutral spec; multiple providers).
• PostHog (managed/self-host, flags + analytics + session replay).

Pattern: server-side evaluation pra flags afetando business logic; client-side só pra UI cosmetic. Cache eval ~30s pra evitar network call per request em hot path.

Database migrations + deploys (orchestration)

Expand-Migrate-Contract:

1. Expand (release N): add column nullable; dual-write old + new.
2. Migrate (release N+1): backfill data; switch reads pra new; mantém dual-write.
3. Contract (release N+2): drop old column; remove dual-write.

-- Release N (expand)
ALTER TABLE orders ADD COLUMN customer_uuid UUID;  -- nullable
-- Release N+1 (migrate): backfill async + dual-write em app
UPDATE orders SET customer_uuid = lookup(customer_id) WHERE customer_uuid IS NULL;
-- Release N+2 (contract)
ALTER TABLE orders DROP COLUMN customer_id;

Online schema migration: gh-ost (GitHub MySQL), pt-online-schema-change (Percona), pg_repack (Postgres). Postgres 11+ otimizou ADD COLUMN ... NOT NULL DEFAULT 'X' (pre-11 fazia rewrite full table). PG 12+ ALTER TABLE non-locking adds frequentemente mais rápido que tooling externo.

Logística applied stack

Stack: K8s + Argo Rollouts + Argo CD + Prometheus + Statsig.

Strategy escolhida pra api-orders: Progressive delivery com analysis gate.

• Steps: 10% → 25% → 50% → 100%, com 10min pause + analysis em cada.
• AnalysisTemplate: success rate > 99.5% AND p99 latency < 300ms (baseline).
• Auto-rollback: error rate > 2% sustained 2min OR p99 > 600ms.
• Feature flags Statsig: tenants enrolled em new_routing_engine per cohort (1% → 10% → 50% → 100%).
• DB migrations: expand-migrate-contract com gates por release; PG 12+ native ALTER pra adds, pg_repack pra rewrites.

Anti-patterns

1. Deploy → manual smoke test → traffic switch (lento + error-prone; automate analysis).
2. Canary 1% em service low-traffic (no statistical signal; analysis sempre falha por ruído).
3. Blue/green com DB migration breaking change (rollback impossible; sempre expand-migrate-contract).
4. Feature flag check em hot path sem cache (network call per request; eval cached 30s).
5. Flag count > 100 sem cleanup process (combinatorial explosion testing; cada flag tem expiry).
6. Auto-rollback threshold tight demais (false positives acordam oncall; calibre vs baseline week).
7. kubectl rollout undo sem validar revisionHistoryLimit (history truncado; old undo impossible).
8. Shadow traffic em service com side effects sem dry-run (emails, payments duplicados).
9. Canary sem user stickiness (user vê v1 e v2 alternando; sticky session via cookie/JWT hash).
10. Deploy com latest tag em image (digest hash mandatório pra reproducibility e rollback determinístico).

Cruza com 03-03 (K8s, Deployment + Service patterns), 03-15 (incident response, deploy correlated to incidents), 03-07 (observability, metrics drive analysis), 04-09 (scaling, blast radius por strategy), 02-10 (ORMs, schema migration patterns).

2.21 Release notes automation + semver discipline

Humanos são péssimos em escrever release notes. Esquecem mudanças, omitem breaking changes, copiam template do release anterior. A solução é gerar tudo a partir dos commits: conventional commits viram changelog, changelog vira version bump, version bump vira tag + GitHub Release. Sem intervenção manual entre git push e o release publicado. Stack 2026 dominante: release-please-action v4 (Google, monorepo + single-repo), @changesets/cli v2.27+ (Atlassian/Vercel, monorepo independent versioning), semantic-release v24+ (alternativa zero-config single-package).

Conventional Commits v1.0.0 spec. Formato fixo: <type>(<scope>)?: <description>. Types canônicos: feat (MINOR bump), fix (PATCH bump), docs, style, refactor, perf, test, build, ci, chore. Breaking change marca com ! após type/scope OU footer BREAKING CHANGE:. Exemplos:

feat(auth): add OAuth2 PKCE flow
fix(api): handle null token on refresh endpoint
feat(api)!: rename /users endpoint to /accounts

BREAKING CHANGE: clients devem migrar pra /accounts; /users responde 410 por 30 dias

Enforce com commitlint (@commitlint/config-conventional) + husky pre-commit hook. PRs com squash-merge: o título do PR vira o commit; configure GitHub branch protection pra exigir título conventional via action amannn/action-semantic-pull-request@v5.

Semver decision tree. Dado mudança X, qual bump?

public API quebrou (signature change, removed export, throw em path antes safe)?
  -> MAJOR (1.2.3 -> 2.0.0)
adicionou feature backward-compatible (novo export, novo param opcional, novo endpoint)?
  -> MINOR (1.2.3 -> 1.3.0)
bug fix sem mudar API (lógica interna, perf, docs)?
  -> PATCH (1.2.3 -> 1.2.4)
ainda em 0.x (unstable)?
  -> regras frouxas: MINOR pode quebrar; > 1.0.0 quando API estabilizar

Internal lib em monorepo: tratar consumers internos como public API. Bump major exige migration guide + janela de coexistência.

Tools comparison — quando cada.

Regra: monorepo Node com pacotes published independently -> changesets. Monorepo polyglot OU repo único -> release-please. Lib npm single-package -> semantic-release.

release-please workflow real (GitHub Actions). Cria "Release PR" agregando commits desde último release; merge -> tag + GitHub Release + CHANGELOG.md commit:

# .github/workflows/release-please.yml
name: release-please
on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

      - uses: actions/checkout@v4
        if: ${{ steps.release.outputs.release_created }}
      - uses: actions/setup-node@v4
        if: ${{ steps.release.outputs.release_created }}
        with: { node-version: '22', registry-url: 'https://registry.npmjs.org' }
      - run: npm ci && npm publish --provenance --access public
        if: ${{ steps.release.outputs.release_created }}
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

release-please-config.json (monorepo lockstep):

{
  "release-type": "node",
  "include-component-in-tag": false,
  "packages": {
    "packages/core": { "package-name": "@acme/core" },
    "packages/cli":  { "package-name": "@acme/cli" }
  },
  "plugins": [{ "type": "node-workspace" }]
}

Changesets workflow (monorepo independent versioning). Dev roda pnpm changeset no PR, escolhe pacotes afetados + bump (patch/minor/major) + descrição. Arquivo .changeset/witty-foxes-dance.md:

---
"@acme/api": minor
"@acme/sdk": patch
---

Add cursor pagination to /events; SDK now retries 429 com exponential backoff.

Action consume changesets no merge:

# .github/workflows/changesets.yml
name: changesets
on: { push: { branches: [main] } }
jobs:
  release:
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write, id-token: write }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with: { node-version: '22', registry-url: 'https://registry.npmjs.org' }
      - run: pnpm install --frozen-lockfile
      - uses: changesets/action@v1
        with:
          publish: pnpm release  # script que roda changeset publish
          version: pnpm version-packages
          commit: "chore: version packages"
          title: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Action abre "Version Packages" PR; merge dispara pnpm release -> bump + publish + tag por pacote.

CHANGELOG.md generation. Nunca escreva à mão. release-please regenera por commit type (Features / Bug Fixes / Performance / BREAKING CHANGES). Changesets usa @changesets/changelog-github pra linkar PR + autor:

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3/schema.json",
  "changelog": ["@changesets/changelog-github", { "repo": "acme/monorepo" }],
  "commit": false,
  "fixed": [],
  "linked": [["@acme/api", "@acme/api-types"]],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@acme/example-app"]
}

linked: pacotes que bumpam juntos (mas independente do resto). fixed: pacotes sempre na mesma versão (lockstep subset).

Prerelease channels (alpha/beta/rc). Pre-1.0 ou breaking releases publicam em dist-tag separada; consumers opt-in:

# changesets prerelease mode
pnpm changeset pre enter beta
pnpm changeset                  # cada PR vira 2.0.0-beta.0, beta.1, ...
pnpm changeset version
pnpm changeset publish          # publica com --tag beta
pnpm changeset pre exit         # finaliza -> 2.0.0

# consumer
npm install @acme/api@beta      # pega 2.0.0-beta.5
npm install @acme/api           # ainda 1.x.x estável

release-please usa release-as no commit footer pra forçar prerelease:

feat: new auth flow

Release-As: 2.0.0-rc.1

Stack Logística aplicada. API freight-api (single-repo Go + Node SDK), release-please em lockstep. Cada PR squash-merged com título feat(routing): add multi-stop optimization -> release-please abre PR chore(main): release 1.7.0 agregando 14 commits desde 1.6.3. CHANGELOG.md auto-gerado: 6 features, 4 fixes, 1 breaking (com migration note). Merge -> tag v1.7.0, GitHub Release com notes, Docker image freight-api:1.7.0 + :1.7 + :1 build no workflow downstream (trigger por release.created). Customer SDK (@logistica/freight-sdk) em changesets independent: bump minor sozinho quando endpoint novo é adicionado, sem forçar major no app principal.

Anti-patterns.

1. Bump major em internal lib sem revisar consumers (breaks 12 apps na segunda; sempre npm why + grep antes).
2. CHANGELOG.md manual coexistindo com auto-gerado (drift inevitável; delete o manual ou desabilite o auto).
3. Commit messages tipo "update stuff", "wip", "fix" sem scope (changelog vira lixo; commitlint enforced).
4. Releases criadas via gh release create direto, bypass do PR (sem audit trail; release-please PR é o registro).
5. Tag rc ou beta em prod por engano (dist-tag confusion; CI valida version.includes('-') -> bloqueia deploy prod).
6. Squash-merge sem normalizar título do PR (commit final perde semântica; action-semantic-pull-request enforced).
7. Breaking change escondida em feat: (consumer toma 500; ! ou footer BREAKING CHANGE: mandatório).
8. 0.x.y por 3 anos com clientes pagantes (semver não aplica abaixo de 1.0; estabilize antes de cobrar SLA).
9. Monorepo lockstep com 40 pacotes (bump em util força republish de tudo; migre pra independent + linked).
10. npm publish sem --provenance (2026 supply chain mínimo; sigstore + GitHub OIDC mandatório).

Cruza com 03-04 §2.10 (versioning + changelog basics), 03-04 §2.13 (artifacts, image tagging), 03-04 §2.18 (mobile pipeline, store versioning), 01-09 (git internals, tag objects + signed tags), 03-15 (incident response — release tags são bisect anchor), 04-08 (microservices contract versioning, gRPC/OpenAPI compat), 03-09 §2.21 (CI/CD pipeline com image build optimization step), 03-17 §2.22 (a11y como deploy gate via axe-playwright + Lighthouse CI), 04-15 §2.20 (npm provenance + Sigstore + GitHub Actions OIDC publish em release flow).

3. Threshold de Maestria

Você precisa, sem consultar:

• Distinguir CI, Continuous Delivery e Continuous Deployment.
• Listar 4 caches que valem em pipeline e estratégia de chave.
• Justificar trunk-based vs GitFlow pra contextos diferentes.
• Comparar 4 deploy strategies em risco e custo.
• Argumentar feature flags vs branch-per-feature.
• Explicar OIDC entre GH Actions e AWS, sem long-lived creds.
• Diferenciar SBOM e signing e por que ambos importam.
• Estratégia pra monorepo CI selectivo.
• Definir DORA metrics e por que importam.
• Plano pra reduzir pipeline de 25 min pra ≤ 10 min.

4. Desafio de Engenharia

Construir o pipeline CI/CD do Logística v1, com promoção até produção em K8s.

Especificação

1. Plataforma:
   • GitHub Actions.
   • Monorepo (apps/api, apps/web, apps/mobile, packages/*).
   • Turborepo ou pnpm filters.
2. Workflow PR:
   • Trigger: PR pra main.
   • Jobs (paralelizar quando possível): install → lint → typecheck → unit → integration (matrix por package afetado).
   • Cache: pnpm store, Turborepo cache, Playwright browsers.
   • Skip de package não tocado.
   • Comment no PR com status e tempo por job.
3. Workflow main merge:
   • Trigger: push em main.
   • Build images (api, web) → push GHCR com tag git-sha + main-latest.
   • Sign com cosign keyless via OIDC.
   • Generate SBOM com syft, attach via cosign attest.
   • Trivy scan; gate em CRITICAL.
4. Deploy staging:
   • Após push image, GitOps: Argo CD detecta nova tag em staging chart values.
   • Smoke test job roda contra staging URL após sync.
   • Falha → rollback automático (Argo).
5. Deploy prod:
   • Manual approval em GitHub Environment "production".
   • Promote: bump tag em prod values, commit, Argo sync.
   • Canary via Argo Rollouts: 10% por 5 min → 50% por 5 min → 100%. Métricas observadas (HTTP 5xx rate); abort se violar.
6. Feature flag:
   • Integre GrowthBook self-hosted ou SaaS.
   • Pelo menos 1 feature em rollout gradual (ex: novo dashboard).
7. Mobile:
   • Workflow pra app courier: lint, test, EAS Build profile staging em PR; profile production em release tag.
   • EAS Update pra OTA em hotfix (com restrição: só JS/asset).
8. Versioning e changelog:
   • Conventional commits enforced (lint via commitlint pre-commit hook).
   • Release Please ou changesets gerando changelog em release.
9. DORA metrics:
   • Em README, demonstre como você capturaria as 4 métricas (manual ou via lib específica).
   • Proponha targets realistas pra Logística.

Restrições

• Sem secrets long-lived em GH Secrets pra cloud (use OIDC).
• Sem latest em deploy prod.
• Sem branch local pra pre-prod (use envs como gate).
• Sem job > 10 min sem caching strategy explícita.

Threshold

• README documenta:
  • Diagrama do pipeline completo (PR → main → staging → prod).
  • Tempos de cada step antes e depois de optimization.
  • Cache hit rate.
  • Demo de canary deployment com métrica abortando rollout (force erro 500 e mostre).
  • Demo de feature flag toggling sem redeploy.
  • Output cosign verify + sbom attest em image.

Stretch

• Self-hosted runners em K8s com ARC (actions-runner-controller).
• Reproducible builds (mesmo input → mesma image, byte a byte).
• SLSA Level 3 provenance attestation.
• Bisect automation: script que dispara CI em N commits pra achar quando uma regressão entrou.
• Hermetic build via Bazel ou Nix.

5. Extensões e Conexões

• Liga com 01-09 (Git): branch protection, signing, conventional commits.
• Liga com 03-01 (testes): suite roda em CI; flakiness é problema CI.
• Liga com 03-02 (Docker): build, scan, sign, push.
• Liga com 03-03 (K8s): GitOps com Argo CD; canary com Argo Rollouts.
• Liga com 03-05 (AWS): OIDC GH → AWS, ECR, deploy targets.
• Liga com 03-06 (IaC): infra deployed via mesmo pipeline (com gates extras).
• Liga com 03-07 (observability): release annotations em Grafana, DORA dashboards.
• Liga com 03-08 (security): supply chain, secrets, gating em vulnerabilities.
• Liga com 04-08 (services vs monolith): monorepo CI; selective deploy.
• Liga com 04-12 (tech leadership): DORA, processo, deployment culture.

6. Referências

• GitHub Actions docs (docs.github.com/en/actions).
• "Continuous Delivery": Jez Humble, David Farley.
• "Accelerate": Forsgren, Humble, Kim (DORA metrics).
• Turborepo docs (turbo.build).
• Argo Rollouts docs (argoproj.github.io/rollouts).
• cosign docs (docs.sigstore.dev/cosign/overview).
• SLSA (slsa.dev).
• Conventional Commits (conventionalcommits.org).
• GrowthBook docs (docs.growthbook.io).
• Charity Majors blog: observability + deployment culture.