Skip to content

Private Repository Setup — runbook

Read in your language: English · Português · Español

Scope status (post-Scope-Freeze 2026-05-10) — See ARCHITECTURE.md for the canonical 37 MÓDULOs + 7 Test Kinds + DOM/CPOS/PIE-PA safety architecture. ADRs 0014, 0019-0025 cover post-Freeze additions.

Status: Active. Repository visibility is PRIVATE as of 2026-05-06. Plan: GitHub Pro.

Onboarding sequence: This is maintainer-only setup (one-time, by the repo owner). Once configured, operators follow: Access → Clone → Install · alternate: Air-gap install.

Why this exists

This project is licensed under PolyForm Noncommercial 1.0.0 + Appendix A — the audience is restricted to Cisco employees and certified partners. A public repository contradicts that audience policy. On 2026-05-06 the repository was moved to private to bring the distribution mechanism into alignment with the license.

This document is the runbook for that change: what was done, why, and how to revert or evolve.

Decisions taken

Decision Choice Trade-off
Repository visibility Private Loses public discovery; aligns with audience policy
GitHub plan Pro ($4/month) Enables branch protection, private Pages, 3000 Actions min/month
Branch protection 8 required checks + 1 review + linear history Friction on every merge — by design
GitHub Pages Public site, private source Operators outside Cisco can read docs; only authorized users see code

What changed in the GitHub Org settings

1. Visibility

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

Verify: 

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

2. Branch protection on main

8 required status checks, 1 required PR approval, linear history mandatory, force-push and deletions blocked, conversation resolution required.

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 is intentional — the sole admin (project owner) needs the ability to push directly in genuine emergencies (incident response, rollback). To temporarily disable protection for an emergency:

# Disable
gh api -X DELETE repos/nollagluiz/AI_forSE/branches/main/protection
# Do the push
git push origin main --force-with-lease  # if needed
# Re-enable using the PUT block above

3. GitHub Pages re-publish

When the repo went private, the existing Pages site was destroyed. Re-publish:

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

Verify with: 

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

The Pages site stays publicly readable (anyone can browse the rendered docs at nollagluiz.github.io/AI_forSE), but the source repository is private. This is intentional — operators and prospective evaluators benefit from public docs; the source is gated.

To make Pages itself private (Pro feature: "Visibility: Private"): 

gh api -X PUT repos/nollagluiz/AI_forSE/pages -f public=false
Decline this unless specifically required — it forces every reader of the docs to authenticate to GitHub.

Day-to-day operations checklist

Every PR touching protected branches must:

  1. ✅ Pass all 8 required status checks
  2. ✅ Receive 1 approving review (codeowner not required)
  3. ✅ Have all PR conversations resolved
  4. ✅ Be merged via squash (linear history required, merge commits blocked)
  5. ✅ Branch deleted after merge (auto-delete enabled)

If a check is consistently failing on main and is not actionable (flaky external dependency, etc.), open an issue first; do not silently remove it from the protection list — that bypasses the audit trail.

Onboarding new authorized users

The license restricts use to "Cisco employees and certified partners". To grant access:

  1. Verify the requester's affiliation (Cisco email or partner certification proof)
  2. Ensure they have signed (or accepted electronically) the License Acceptance Modal at first login (see LicenseAcceptanceModal.tsx flow)
  3. Add as collaborator with pull (read) permission: 
    gh api -X PUT repos/nollagluiz/AI_forSE/collaborators/{username} -f permission=pull
  4. Promote to push only if they will actively contribute, and only after CLA signature (when CLA is implemented)

Revoking access

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

Audit the access log periodically: 

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

What this does NOT protect against

  • Authorized users copying source code to a personal device — solved by NDAs, not GitHub
  • Authorized users contributing to derivative public projects — solved by CLA + license enforcement
  • A leaked clone surfacing on another platform — solved by DMCA + forensic fingerprinting (planned)

This runbook is one layer. The license terms (PolyForm + Appendix A) are the legal layer. Forensic fingerprinting and CLA are pending follow-up tasks tracked separately.

Reverting to public

If audience policy changes and the repo needs to be public again:

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

Branch protection rules survive the visibility change. Pages will need to be reconfigured if it was set to private.