GitHub Actions avançado com Claude Code: permissões, OIDC, cache e matrix CI

GitHub Actions é simples quando a meta é apenas rodar testes depois de um push. O desafio real aparece quando o time precisa de permissões mínimas, cache confiável, testes em múltiplos ambientes, deploy em cloud sem chave longa e revisão com Claude Code sem expor secrets.

Este guia usa Claude Code como parceiro de desenho do workflow, não como gerador automático de YAML. Os exemplos são workflows completos que você pode copiar, ajustar e executar. A parte importante é revisar por que cada job precisa de cada permission, quais secrets ele pode ler e o que acontece quando o pull request vem de um fork.

Conferi as recomendações com a documentação oficial do GitHub sobre workflow syntax, GITHUB_TOKEN permissions, AWS OIDC, dependency caching, concurrency e Claude Code GitHub Actions.

Arquitetura

Um workflow avançado não é aquele que automatiza tudo. É o que reduz o raio de impacto, deixa falhas fáceis de diagnosticar, cancela execuções antigas e mantém aprovação humana em mudanças de produção.

flowchart LR
  PR["Pull request"] --> Gate["matrix test and lint"]
  Gate --> Cache["lockfile cache"]
  Gate --> Claude["Claude Code review"]
  Gate --> Deploy["OIDC deploy"]
  Deploy --> Env["GitHub environment approval"]
  Env --> AWS["AWS role"]

Alguns termos precisam estar claros. Matrix é uma tabela de combinações, por exemplo Node.js 22 e 24 em Ubuntu e Windows. OIDC, OpenID Connect, troca uma identidade temporária do GitHub Actions por credenciais cloud de curta duração. Assim você não guarda AWS access keys longas no GitHub Secrets. Concurrency controla execuções simultâneas. Permissions define o que o GITHUB_TOKEN pode fazer.

Casos de uso

O primeiro caso é um gate de qualidade para pull request. Lint, type-check e testes rodam em mais de um ambiente antes do merge. Isso detecta problemas de path no Windows, diferenças de runtime Node.js e lockfile inconsistente.

O segundo caso é deploy para staging. Depois que main passa, GitHub Actions assume um IAM role da AWS por OIDC e faz deploy sem chave estática. Em produção, adicione aprovação com GitHub Environment.

O terceiro caso é CI compartilhado em monorepo. Se vários packages repetem o mesmo Node setup, install e test, um reusable workflow evita drift de versão entre arquivos YAML.

O quarto caso é revisão de PR com Claude Code. Comece com leitura e comentários. Permissões de escrita só devem entrar depois de branch protection, revisão obrigatória e plano de rollback.

Prompt para Claude Code

Peça desenho com restrições antes de pedir o arquivo.

Design GitHub Actions for this repository.
The goals are pull request quality gates, staging deployment, and Claude Code review.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions.
- Use OIDC for AWS. Do not store long-lived AWS access keys in Secrets.
- Include package-lock.json in dependency cache keys.
- Assume secrets are not available on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Produce GitHub Actions YAML that is valid as written.

End with concrete failure cases and verification steps.

Esse prompt obriga Claude Code a explicar decisões de segurança em vez de só preencher um template.

Gate de qualidade de PR

Este workflow usa actions/checkout@v6 e actions/setup-node@v6, versões major atuais em junho de 2026. Runners hospedados pelo GitHub normalmente funcionam direto. Se você usa self-hosted runners, confirme primeiro a versão do runner.

name: pr-quality-gate

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: pr-quality-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: node-${{ matrix.node }}-${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [22, 24]

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

O job precisa apenas de contents: read, porque não escreve no repositório. concurrency cancela runs antigos do mesmo branch. O cache fica ligado ao package-lock.json; evite cachear node_modules inteiro sem motivo forte, porque módulos nativos e diferenças de OS podem quebrar o build.

Deploy para AWS com OIDC

O padrão seguro é registrar GitHub como OIDC provider na AWS, criar um IAM role limitado e restringir a trust policy por repository, branch ou environment. No workflow, id-token: write é necessário para solicitar o token OIDC.

name: deploy-staging

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    environment: staging

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/claude-code-github-actions-staging
          aws-region: ap-northeast-1

      - name: Verify caller identity
        run: aws sts get-caller-identity

      - name: Deploy
        run: |
          npm ci
          npm run build
          echo "Deploy command goes here"

Troque o role ARN, a região e o comando de deploy. Para produção, use outro environment e reviewers obrigatórios.

Reusable workflow

Um reusable workflow é útil quando vários workflows repetem a mesma verificação. Ele também evita que versões antigas de actions fiquem perdidas em arquivos diferentes.

# .github/workflows/reusable-node-check.yml
name: reusable-node-check

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install
        run: npm ci

      - name: Check
        run: |
          npm run lint
          npm run typecheck
          npm test

Workflow que chama:

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  node-check:
    uses: ./.github/workflows/reusable-node-check.yml
    with:
      node-version: "24"

Não esconda diferenças reais dentro de um reusable workflow gigante. Se cada package tem comandos próprios, peça ao Claude Code para separar setup comum e passos específicos.

Revisão de PR com Claude Code

Claude Code Action v1 usa anthropics/claude-code-action@v1, prompt e claude_args. Não copie exemplos antigos com @beta ou direct_prompt.

name: claude-pr-review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Claude Code review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request as a senior engineer.
            Focus on security, broken tests, unnecessary permissions, and missing verification.
            Do not modify files. Leave concise review comments only.
          claude_args: |
            --max-turns 5

O if pula forks, porque secrets do repositório normalmente não estão disponíveis neles. Para aceitar forks, crie um caminho separado de baixa confiança sem secrets e sem executar código externo com permissões altas.

Falhas comuns

A falha mais perigosa é usar pull_request_target e fazer checkout do head do PR. Esse evento pode rodar com permissões próximas ao repositório base, então executar código de fork externo vira risco sério.

Outra falha é imprimir secrets para depurar. GitHub mascara muitos valores exatos, mas strings derivadas, JSON, base64 e logs de ferramentas externas ainda podem vazar. Passe para Claude Code nomes e finalidades dos secrets, nunca valores.

Cache também pode quebrar build. Uma key ampla como node-cache pode restaurar dependências antigas depois de mudar o lockfile. Use cache-dependency-path ou hashFiles('**/package-lock.json').

Matrix pode crescer rápido. Dois OS por duas versões de Node.js é razoável; três OS, quatro runtimes e oito packages viram 96 jobs. Rode matriz pequena em PR e cobertura ampla em nightly.

Por fim, acompanhe versões major de actions. Em 2026, muitas actions oficiais usam runtimes Node mais novos. Com self-hosted runners, atualize o runner antes do workflow.

Caminho de monetização

CI seguro ajuda páginas que geram receita: landing pages, templates pagos, checkout, formulários de leads e conteúdo de curso podem sair em PRs menores, com menos risco de deploy quebrado ou secret vazado. Para começar sozinho, use o cheatsheet gratuito de Claude Code. Para times que precisam desenhar permissions, OIDC, revisão com Claude Code, branch protection e CI de monorepo em um repositório real, veja treinamento e consultoria Claude Code.

Resultado verificado

Para este artigo, extraí os blocos YAML do MDX e validei com um parser YAML. Os exemplos são lidos como YAML e cobrem on, permissions, concurrency, matrix, reusable workflow, deploy OIDC e Claude Code Action v1. Antes de rodar, substitua AWS role ARN, scripts npm, environment e secret ANTHROPIC_API_KEY.