Exemplos de implementação da governação PR com templates, verificações, CODEOWNERS, regras e portas de ambiente

Nesta unidade, você aprenderá:

• Como os pull requests funcionam como pontos de controlo arquitetónico para a execução de agentes

• Como aplicar a validação do plano com verificações obrigatórias e verificações de estado

• Como usar os CODEOWNERS e as revisões para encaminhar e aprovar alterações

Os pull requests são pontos de controlo arquitetónico

Os pull requests são o principal mecanismo de controlo para a execução de agentes no GitHub. Em vez de permitir alterações diretas a branches protegidas, arquiteturas bem desenhadas encaminham as alterações dos agentes através de pull requests e impõem requisitos de fusão através de políticas.

Um fluxo de trabalho seguro comum é o seguinte:

Agent creates branch

    ↓

Agent opens pull request (includes plan)

    ↓

Required reviews validate approach

    ↓

GitHub Actions run required checks

    ↓

All checks pass + approvals complete

    ↓

Pull request can be merged

Esta estrutura assegura que a execução é limitada tanto pela automação como pela revisão humana.

Implementação: Modelo de RP que requer um plano estruturado

Um modelo de pull request garante que cada agente de residência permanente fornece secções consistentes de plano e provas.

<!-- File: .github/pull_request_template.md -->

## Plan (required)
- **Goal:**
- **Scope (paths/files):**
- **Steps:**
  1.
  2.
  3.
- **Success criteria (verifiable):**
  - [ ] Required checks pass
  - [ ] Security signals reviewed (as applicable)
- **Risks + mitigations:**
- **Rollback / escalation plan:**

## Evidence
- Workflow run(s):
- Scan results (if applicable):

## Review checklist
- [ ] Plan reviewed and approved
- [ ] Required reviews satisfied
- [ ] Required checks satisfied

Fazer cumprir a validação do plano com verificações obrigatórias e verificações de estado

Para além dos modelos, pode impor o bloqueio de planos como uma verificação de estado obrigatória. Isto transforma uma expectativa de processo ("incluir um plano") numa garantia do sistema.

# File: .github/workflows/plan-gate.yml
name: Plan Gate

on:
  pull_request:
    branches: [ main ]

jobs:
  require-plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Require plan artifact
        run: |
          if [ ! -f "Github/pull_request_template.md" ]; then
            echo "Github/pull_request_template.md is required for this pull request."
            exit 1
          fi
          echo "Github/pull_request_template.md found."

Nota de implementação:

Um administrador de repositório pode definir o Plan Gate como uma verificação de estado obrigatória usando regras de proteção de ramos, garantindo que os PRs não possam ser fundidos a menos que o plano exista.

O GitHub pode exigir aprovação explícita antes de os fluxos de trabalho serem executados com alterações geradas por agentes.

Utilização do CODEOWNERS para garantir a segurança

O CODEOWNERS assegura que as alterações em áreas sensíveis sejam automaticamente enviadas pelos revisores certos.

# File: CODEOWNERS

/security/ @security-team
/.github/workflows/ @platform-team
/infra/ @platform-team
* @core-team

Isto garante que um plano e conjunto de alterações que afetam caminhos de alto risco não possam ser fundidos sem visibilidade dos especialistas certos (quando combinados com políticas de revisão obrigatórias).

Tenha cuidado com a execução sem validação

Se um agente conseguir contornar as verificações obrigatórias ou fundir sem revisões, a arquitetura perde os seus principais mecanismos de segurança. Isto é menos um problema de modelo e mais uma falha no design do fluxo de trabalho.

Conclusão principal: Os pull requests não são apenas ferramentas de colaboração – são mecanismos de fiscalização.

De seguida, vai definir quanta autonomia o agente deve ter com base no risco da tarefa.