Ejemplos de implementación de gobernanza de PR con plantillas, verificaciones, CODEOWNERS, reglas y puertas de entorno

En esta unidad, aprenderá lo siguiente:

• Cómo los pull requests actúan como puntos de control arquitectónicos para la ejecución de agentes

• Aplicación de la validación del plan con comprobaciones de estado necesarias

• Cómo usar CODEOWNERS y revisiones para enrutar y aprobar cambios

Las solicitudes de incorporación de cambios son puntos de control arquitectónicos

Las solicitudes de incorporación de cambios (pull requests) son el principal mecanismo de control para la ejecución de agentes en GitHub. En lugar de permitir cambios directos en ramas protegidas, las arquitecturas bien diseñadas dirigen los cambios del agente a través de solicitudes de incorporación de cambios y aplican los requisitos de combinación a través de la política.

Un flujo de trabajo seguro común tiene este aspecto:

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 estructura garantiza que la ejecución esté controlada por la automatización y la revisión humana.

Implementación: plantilla de PR que requiere un plan estructurado

** Una plantilla de solicitud de incorporación de cambios garantiza que cada PR del agente incluya secciones de plan y evidencia coherentes.

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

Aplicación de la validación del plan con comprobaciones de estado necesarias

Además de las plantillas, puede implementar el bloqueo del plan como una comprobación de estado obligatoria. Esto convierte una expectativa de proceso ("incluir un plan") en una garantía del 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 implementación:

Un administrador de repositorios puede marcar Plan Gate como una comprobación de estado obligatoria mediante la protección de ramas/conjuntos de reglas, lo que garantiza que los pull requests no se pueden fusionar a menos que exista el plan.

GitHub puede requerir aprobación explícita antes de que los flujos de trabajo se ejecuten en los cambios generados por el agente.

Uso de CODEOWNERS para garantizar la seguridad

CODEOWNERS garantiza que los cambios en las áreas confidenciales vayan automáticamente a los revisores correctos.

# File: CODEOWNERS

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

Esto garantiza que un plan y un conjunto de cambios que afecten a las rutas de acceso de alto riesgo no se puedan combinar sin visibilidad de los expertos adecuados (cuando se combinan con las directivas de revisión necesarias).

Tenga cuidado con la ejecución sin validación.

Si un agente puede omitir las comprobaciones necesarias o combinar sin revisiones, la arquitectura pierde sus mecanismos de seguridad principales. Esto es menos un problema de modelo y más un error de diseño de flujo de trabajo.

Conclusiones clave: Las solicitudes de incorporación de cambios no son solo herramientas de colaboración, sino que son mecanismos de cumplimiento.

A continuación, definirá la autonomía que debe tener el agente en función del riesgo de la tarea.