Skip to content

Configuración de Repositorio Privado — runbook

Lee en tu idioma: English · Português · Español

Estado del alcance (post-congelación de alcance 2026-05-10) — Ver ARCHITECTURE.md para los 37 MÓDULOs canónicos + 7 Test Kinds + arquitectura de safety DOM/CPOS/PIE-PA. ADRs 0014, 0019-0025 cubren adiciones post-Freeze.

Secuencia de onboarding: Este es setup solo del mantenedor (una vez, por el dueño del repo). Una vez configurado, los operadores siguen: Acceso → Clone → Instalar · alternativa: Instalación air-gap.> Estado: Activo. La visibilidad del repositorio es PRIVATE desde 2026-05-06. Plan: GitHub Pro.

Por qué existe esto

Este proyecto está licenciado bajo PolyForm Noncommercial 1.0.0 + Appendix A — la audiencia está restringida a empleados de Cisco y partners certificados. Un repositorio público contradice esa política de audiencia. El 2026-05-06 el repositorio fue movido a privado para alinear el mecanismo de distribución con la licencia.

Este documento es el runbook de ese cambio: qué se hizo, por qué, y cómo revertir o evolucionar.

Decisiones tomadas

Decisión Elección Trade-off
Visibilidad del repositorio Privado Pierde discoverability pública; alinea con política de audiencia
Plan GitHub Pro ($4/mes) Habilita branch protection, Pages privado, 3000 min/mes de Actions
Branch protection 8 checks obligatorios + 1 review + linear history Fricción en cada merge — por diseño
GitHub Pages Sitio público, source privado Operadores fuera de Cisco leen docs; solo usuarios autorizados ven el código

Qué cambió en la configuración del Org GitHub

1. Visibilidad

gh repo edit nollagluiz/AI_forSE --visibility private --accept-visibility-change-consequences

Verificar: 

gh repo view nollagluiz/AI_forSE --json visibility,isPrivate
# esperado: {"visibility":"PRIVATE","isPrivate":true}

2. Branch protection en main

8 status checks obligatorios, 1 review aprobado obligatorio, linear history obligatorio, force-push y deletions bloqueados, conversaciones obligatoriamente resueltas.

gh api -X PUT repos/nollagluiz/AI_forSE/branches/main/protection --input - <<'EOF'
{
  "required_status_checks": {
    "strict": true,
    "contexts": [
      "dashboard — typecheck, lint, test, build",
      "agent — typecheck & test",
      "go — vet & test (persona-seeder, mock-engine, har-engine) (persona-seeder)",
      "go — vet & test (persona-seeder, mock-engine, har-engine) (mock-engine)",
      "go — vet & test (persona-seeder, mock-engine, har-engine) (har-engine)",
      "gitleaks",
      "trivy — dashboard",
      "dashboard — license compliance"
    ]
  },
  "enforce_admins": false,
  "required_pull_request_reviews": {
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": false,
    "required_approving_review_count": 1,
    "require_last_push_approval": false
  },
  "restrictions": null,
  "required_linear_history": true,
  "allow_force_pushes": false,
  "allow_deletions": false,
  "required_conversation_resolution": true,
  "lock_branch": false,
  "required_signatures": false
}
EOF

enforce_admins: false es intencional — el único admin (propietario del proyecto) necesita la capacidad de hacer push directo en emergencias reales (respuesta a incidente, rollback). Para deshabilitar temporalmente la protección en una emergencia:

# Deshabilitar
gh api -X DELETE repos/nollagluiz/AI_forSE/branches/main/protection
# Hacer el push
git push origin main --force-with-lease  # si es necesario
# Re-habilitar usando el bloque PUT de arriba

3. Re-publicar GitHub Pages

Cuando el repo se hizo privado, el sitio Pages existente fue destruido. Re-publicar:

gh api -X POST repos/nollagluiz/AI_forSE/pages -f build_type=workflow
gh workflow run docs.yml

Verificar con: 

curl -s -o /dev/null -w "%{http_code}\n" https://nollagluiz.github.io/AI_forSE/
# esperado: 200

El sitio Pages permanece públicamente legible (cualquiera navega los docs renderizados en nollagluiz.github.io/AI_forSE), pero el repositorio-fuente es privado. Esto es intencional — operadores y potenciales evaluadores se benefician de docs públicos; el código fuente está restringido.

Para hacer Pages en sí privado (feature del Pro: "Visibility: Private"): 

gh api -X PUT repos/nollagluiz/AI_forSE/pages -f public=false
No hagas esto a menos que sea específicamente requerido — fuerza a todo lector de los docs a autenticarse en GitHub.

Checklist de operaciones día-a-día

Todo PR tocando branches protegidas debe:

  1. ✅ Pasar los 8 status checks obligatorios
  2. ✅ Recibir 1 review aprobado (codeowner no obligatorio)
  3. ✅ Tener todas las conversaciones del PR resueltas
  4. ✅ Ser mergeado vía squash (linear history obligatorio, merge commits bloqueados)
  5. ✅ Branch eliminada tras merge (auto-delete habilitado)

Si un check está fallando consistentemente en main y no es accionable (dependencia externa flaky, etc.), abre un issue antes; no lo remuevas silenciosamente de la lista de protección — eso evade la traza de auditoría.

Onboarding de nuevos usuarios autorizados

La licencia restringe el uso a "empleados de Cisco y partners certificados". Para otorgar acceso:

  1. Verificar la afiliación del solicitante (email Cisco o prueba de certificación de partner)
  2. Asegurar que haya firmado (o aceptado electrónicamente) el License Acceptance Modal en el primer login (ver flujo en LicenseAcceptanceModal.tsx)
  3. Añadir como colaborador con permiso pull (read): 
    gh api -X PUT repos/nollagluiz/AI_forSE/collaborators/{username} -f permission=pull
  4. Promover a push solo si va a contribuir activamente, y solo tras la firma del CLA (cuando el CLA se implemente)

Revocar acceso

gh api -X DELETE repos/nollagluiz/AI_forSE/collaborators/{username}

Auditar el log de acceso periódicamente: 

gh api repos/nollagluiz/AI_forSE/collaborators --jq '[.[]|{login,permissions}]'

Lo que esto NO protege

  • Usuarios autorizados copiando código fuente a dispositivo personal — se resuelve con NDAs, no con GitHub
  • Usuarios autorizados contribuyendo a proyectos derivados públicos — se resuelve con CLA + enforcement de licencia
  • Un clone filtrado apareciendo en otra plataforma — se resuelve con DMCA + fingerprinting forense (planificado)

Este runbook es una capa. Los términos de la licencia (PolyForm + Appendix A) son la capa legal. Fingerprinting forense y CLA son tareas de follow-up pendientes, rastreadas por separado.

Revertir a público

Si la política de audiencia cambia y el repo necesita volver a ser público:

gh repo edit nollagluiz/AI_forSE --visibility public --accept-visibility-change-consequences

Las reglas de branch protection sobreviven al cambio de visibilidad. Pages necesitará reconfigurarse si estaba configurado como privado.

Relacionados