Habilidade Avançada em GitHub Actions

Orientação especializada para projetar, escrever, depurar e proteger fluxos de trabalho de nível de produção no GitHub Actions.

Guia Detalhado

Leia o guia detalhado antes de executar esta habilidade. Ele contém o procedimento completo e o material de referência. Trate seus requisitos de segurança, pré-requisitos e validação como obrigatórios. Para trabalho focado, carregue as seções relevantes; para trabalho de ponta a ponta, leia o guia completamente.

Quando Usar Esta Habilidade

• O usuário menciona GitHub Actions, .github/workflows, pipelines de CI/CD, runners, jobs, steps ou actions
• O usuário quer automatizar builds, testes, deployments ou releases via GitHub
• O usuário pergunta sobre builds de matriz, fluxos de trabalho reutilizáveis, actions compostas ou runners auto-hospedados
• O usuário precisa de ajuda com autenticação OIDC, estratégias de cache ou gerenciamento de segredos
• O usuário diz "meu pipeline do GitHub está falhando" ou "configurar CI para meu repositório"
• O usuário pergunta sobre segurança de fluxo de trabalho, hardening ou regras de proteção de ambiente

Quando NÃO Usar Esta Habilidade

• O usuário está trabalhando com GitLab CI/CD → recomende gitlab-ci-patterns
• O usuário está trabalhando com CircleCI, Jenkins ou outras plataformas de CI
• A tarefa é puramente sobre construção de imagem Docker sem contexto do GitHub → recomende docker-expert
• A tarefa é sobre configuração de deployment do Kubernetes → recomende kubernetes-architect

Hardening de Segurança

1. Sempre Declare Permissões (Menor Privilégio)

# Workflow-level default — restrict everything
permissions:
  contents: read

jobs:
  publish:
    # Job-level override — only expand what's needed
    permissions:
      contents: write        # Only for release/publish jobs
      packages: write        # Only for container push jobs
      pull-requests: write   # Only for PR comment jobs
      id-token: write        # Only for OIDC auth jobs

2. Fixe Actions de Terceiros para SHA de Commit Completo

# ❌ UNSAFE — tag can be mutated or hijacked
- uses: actions/checkout@v4

# ✅ SAFE — commit SHA is immutable
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

# Tool to automate SHA pinning:
# npx pin-github-action .github/workflows/*.yml
# or: pip install ratchet && ratchet pin .github/workflows/

3. Previna Injeção de Script

# ❌ UNSAFE — attacker controls PR title, which gets expanded in shell
- run: echo "${{ github.event.pull_request.title }}"

# ✅ SAFE — pass through environment variable (shell doesn't evaluate it)
- env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: echo "$PR_TITLE"

# ✅ SAFE — expressions in if: conditions are evaluated by Actions, not shell
- if: github.event.pull_request.draft == false
  run: echo "Not a draft"

Nunca coloque ${{ ... }} diretamente dentro de run: quando o valor pode vir de metadados de PR, inputs de fluxo de trabalho, arquivos de repositório, JSON de matriz ou saídas de jobs anteriores. Coloque-o em env: primeiro, valide os valores permitidos sempre que possível e referencie a variável shell com aspas.

4. Restrinja o Uso de pull_request_target

# Only run when a maintainer adds a specific label — prevents untrusted execution
on:
  pull_request_target:
    types: [labeled]

jobs:
  validate:
    # Double-guard: check label name AND author_association
    if: |
      github.event.label.name == 'safe-to-test' &&
      (github.event.pull_request.author_association == 'COLLABORATOR' ||
       github.event.pull_request.author_association == 'MEMBER' ||
       github.event.pull_request.author_association == 'OWNER')

5. Proteja com StepSecurity

# Add to every workflow — hardens runner, monitors outbound traffic
- uses: step-security/harden-runner@4d991eb9995541a0b71d1b66f1f98a5f1bef422c  # v2.11.0
  with:
    egress-policy: audit          # Start with 'audit', move to 'block' after confirming allowlist
    allowed-endpoints: >
      api.github.com:443
      registry.npmjs.org:443
      objects.githubusercontent.com:443

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Sempre teste fluxos de trabalho reutilizáveis em um branch de recurso antes de mesclar para o main.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem faltando.