Exemplos de implementação da governança de PR com modelos, verificações, CODEOWNERS, regras e portões de ambiente

Nesta unidade, você aprenderá:

• Como as solicitações de pull atuam como pontos de controle de arquitetura para execução do agente

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

• Como usar CODEOWNERS e revisões para direcionar e aprovar alterações

Solicitações de pull são pontos de controle de arquitetura

As solicitações de pull são o mecanismo de controle primário para execução do agente em GitHub. Em vez de permitir alterações diretas em branches protegidos, arquiteturas bem projetadas roteiam alterações de agente por meio de pull requests e impõem requisitos de mesclagem por meio de políticas.

Um fluxo de trabalho seguro comum tem esta aparência:

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

Essa estrutura garante que a execução seja controlada tanto pela automação quanto pela revisão humana.

Implementação: modelo de PR que requer um plano estruturado

Um modelo de solicitação de pull garante que cada PR do agente forneça seções de plano e evidência consistentes.

<!-- 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

Impor a validação do plano com verificações de status necessárias

Além dos modelos, você pode impor o gating do plano como uma verificação de status necessária. Isso transforma uma expectativa de processo ("incluir um plano") em uma 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."

Observação de implementação:

Um administrador de repositório pode definir o "Plan Gate" como uma verificação de status necessária usando conjuntos de regras ou proteção de branch, garantindo que os PRs não possam ser mesclados, a menos que o plano esteja presente.

GitHub pode exigir aprovação explícita antes que os fluxos de trabalho sejam executados em alterações geradas pelo agente.

Usando CODEOWNERS para garantir a segurança

CODEOWNERS garante que as alterações em áreas sensíveis sejam automaticamente direcionadas aos revisores adequados.

# File: CODEOWNERS

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

Isso garante que um plano e um conjunto de alterações que afetem caminhos de alto risco não possam ser mesclados sem visibilidade dos especialistas certos (quando combinados com as políticas de revisão necessárias).

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

Se um agente puder ignorar as verificações necessárias ou mesclar sem revisões, a arquitetura perderá seus principais mecanismos de segurança. Isso é menos um problema de modelo e mais uma falha de design de fluxo de trabalho.

Principais conclusões: Pull requests não são apenas ferramentas de colaboração - são mecanismos de aplicação.

Em seguida, você definirá quanta autonomia o agente deve ter com base no risco da tarefa.