Skip to content

Setup do Repositório Privado — runbook

Leia no seu idioma: English · Português · Español

Status do escopo (pós-congelamento de escopo 2026-05-10) — Ver ARCHITECTURE.md para os 37 MÓDULOs canônicos + 7 Test Kinds + arquitetura de safety DOM/CPOS/PIE-PA. ADRs 0014, 0019-0025 cobrem adições pós-Freeze.

Sequência de onboarding: Este é setup somente do mantenedor (uma vez, pelo dono do repo). Depois de configurado, operadores seguem: Acesso → Clone → Instalar · alternativa: Instalação air-gap.> Status: Ativo. Visibilidade do repositório é PRIVATE desde 2026-05-06. Plano: GitHub Pro.

Por que isso existe

Este projeto está licenciado sob PolyForm Noncommercial 1.0.0 + Appendix A — a audiência é restrita a funcionários da Cisco e parceiros certificados. Um repositório público contradiz essa política de audiência. Em 2026-05-06 o repositório foi movido para privado para alinhar o mecanismo de distribuição com a licença.

Este documento é o runbook dessa mudança: o que foi feito, por quê, e como reverter ou evoluir.

Decisões tomadas

Decisão Escolha Trade-off
Visibilidade do repositório Privado Perde discoverability pública; alinha com política de audiência
Plano GitHub Pro ($4/mês) Habilita branch protection, Pages privada, 3000 min/mês de Actions
Branch protection 8 checks obrigatórios + 1 review + linear history Atrito em todo merge — por design
GitHub Pages Site público, source privado Operadores fora da Cisco leem docs; só usuários autorizados veem o código

O que mudou nas configurações da Org GitHub

1. Visibilidade

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 na main

8 status checks obrigatórios, 1 review aprovado obrigatório, linear history obrigatório, force-push e deletions bloqueados, conversas obrigatoriamente resolvidas.

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 é intencional — o único admin (proprietário do projeto) precisa da capacidade de fazer push direto em emergências reais (resposta a incidente, rollback). Para desabilitar temporariamente a proteção em uma emergência:

# Desabilitar
gh api -X DELETE repos/nollagluiz/AI_forSE/branches/main/protection
# Fazer o push
git push origin main --force-with-lease  # se necessário
# Reabilitar usando o bloco PUT acima

3. Republicar GitHub Pages

Quando o repo virou privado, o site Pages existente foi destruído. Republicar:

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

Verificar com: 

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

O site Pages permanece publicamente legível (qualquer um navega nos docs renderizados em nollagluiz.github.io/AI_forSE), mas o repositório-fonte é privado. Isso é intencional — operadores e potenciais avaliadores se beneficiam de docs públicos; o source-code é gateado.

Para tornar a Pages em si privada (feature do Pro: "Visibility: Private"): 

gh api -X PUT repos/nollagluiz/AI_forSE/pages -f public=false
Não faça isso a menos que seja especificamente requerido — força todo leitor dos docs a autenticar no GitHub.

Checklist de operações dia-a-dia

Todo PR tocando branches protegidas precisa:

  1. ✅ Passar nos 8 status checks obrigatórios
  2. ✅ Receber 1 review aprovado (codeowner não obrigatório)
  3. ✅ Ter todas as conversas do PR resolvidas
  4. ✅ Ser mergeado via squash (linear history obrigatório, merge commits bloqueados)
  5. ✅ Branch deletada após merge (auto-delete habilitado)

Se um check estiver falhando consistentemente na main e não for acionável (dependência externa flaky, etc.), abra uma issue antes; não remova ele silenciosamente da lista de proteção — isso burla a trilha de auditoria.

Onboarding de novos usuários autorizados

A licença restringe uso a "funcionários da Cisco e parceiros certificados". Para conceder acesso:

  1. Verificar a afiliação do solicitante (e-mail Cisco ou prova de certificação de parceiro)
  2. Garantir que ele tenha assinado (ou aceitado eletronicamente) o License Acceptance Modal no primeiro login (ver fluxo em LicenseAcceptanceModal.tsx)
  3. Adicionar como colaborador com permissão pull (read): 
    gh api -X PUT repos/nollagluiz/AI_forSE/collaborators/{username} -f permission=pull
  4. Promover para push apenas se ele for ativamente contribuir, e somente após assinatura do CLA (quando o CLA for implementado)

Revogando acesso

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

Auditar o log de acesso periodicamente: 

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

O que isto NÃO protege

  • Usuários autorizados copiando código-fonte para dispositivo pessoal — resolvido com NDAs, não com GitHub
  • Usuários autorizados contribuindo para projetos derivados públicos — resolvido com CLA + enforcement de licença
  • Um clone vazado aparecendo em outra plataforma — resolvido com DMCA + fingerprinting forense (planejado)

Este runbook é uma camada. Os termos da licença (PolyForm + Appendix A) são a camada legal. Fingerprinting forense e CLA são tarefas de follow-up pendentes, rastreadas separadamente.

Revertendo para público

Se a política de audiência mudar e o repo precisar voltar a ser público:

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

Regras de branch protection sobrevivem à mudança de visibilidade. Pages precisará ser reconfigurada se estava configurada como privada.

Relacionados