documentation/PRD Drafts/git-repo-setup-peer-review.md

Git Repo Setup & Peer Review PRD

Status: Draft — Pending Commander Bobby Review Author: Artemis Date: 2026-06-03

---

1. Purpose & Scope

This PRD defines the standard Git repository setup for all Iron Legion Labs projects hosted on Gitea. Every new repo — whether fleet config, documentation, or service-specific — must follow this pattern so that drafts live in forks/PRs and canonical docs live on protected branches.

In scope:

• Branch protection rules (mandatory)
• Fork + PR workflow for documentation and PRDs
• Credential/token management for CI/automation
• Gitea API token reference for Artemis automation

Out of scope:

• Code review style guides (covered per-project)
• CI/CD pipeline definitions (separate PRDs)

---

2. Success Criteria

#	Criterion	How Verified
1	Every new repo has main branch protected on creation	API query or UI inspection
2	Direct push to main is blocked without PR + review	Attempt push, expect 403 or pre-receive hook rejection
3	All PRDs and docs go through fork → PR → review → merge	Git log shows merge commits from PRs
4	Artemis can automate via Gitea API using stored R/W token	curl -H "Authorization: token ..." returns 200

---

3. Gitea Token Reference

Tokens are stored in two places depending on scope:

Token	Purpose	Storage	Scope
gitea_deploy_token	Read-only for ansible-pull nodes	/home/jarvis/.ansible/secrets/deploy_token	repo:read
gitea_rw_token	Read-write for Artemis automation	/home/jarvis/.ansible/secrets/deploy_token	repo:write, organization

Both are also mirrored to: ~/.hermes/credentials/fleet.env (mode 600) for runtime access by Artemis.

---

4. Branch Protection Rules (Mandatory for Every Repo)

Apply these rules to the main branch on repo creation:

Setting	Value	Why
Enable branch protection	✅ ON	Prevents accidental force-push
Require pull request reviews	✅ ON, minimum 1 approver	Ensures human review
Dismiss stale approvals	✅ ON	Re-review after new commits
Block merge without approval	✅ ON	No self-merge loophole
Enable push whitelist	✅ ON, deploy keys only	CI can push; humans cannot
Require status checks	❌ OFF (until CI is configured)	No false blocking

API method (for Artemis automation):

curl -sk "https://gitea.nb.bobbysh.me/api/v1/repos/<org>/<repo>/branch_protections" \
  -H "Authorization: token $GITEA_RW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_name": "main",
    "required_approvals": 1,
    "enable_approvals_whitelist": false,
    "enable_merge_whitelist": false,
    "enable_push": true,
    "enable_push_whitelist": true,
    "push_whitelist_deploy_keys": true,
    "enable_pr": true
  }'

UI method (for manual setup):

1. Repo → Settings → Branches → main → Add Protection Rule
2. Check the boxes above → Save

---

5. Draft → Canon Workflow

┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│   PRD Draft │ ───▶ │   Fork/PR    │ ───▶ │   Review     │
│   PRD Drafts/│      │   (any dev)  │      │   (Bobby)    │
└─────────────┘      └──────────────┘      └──────┬───────┘
                                                   │
                           ┌───────────────────────▼───────┐
                           │   Approved → merge to main   │
                           │   Move file: PRD Drafts/ →   │
                           │   PRDs/ (canonical)          │
                           └──────────────────────────────┘

For Artemis (automation):

• Drafts are written to PRD Drafts/ directly during active work sessions
• Bobby approves → Artemis moves to PRDs/ in a follow-up commit
• No PR needed for Artemis-authored drafts (Bobby reviews inline)

For F.R.I.D.A.Y. / human contributors:

• Fork the repo
• Push draft to fork branch
• Open PR against main
• Bobby (or designated reviewer) approves
• Merge → file lands in PRDs/

---

6. Repo Setup Checklist

Use this for every new repo:

• Create repo under Iron-Legion/ org
• Initialize with main branch only (delete master if auto-created)
• Apply branch protection rules (Section 4)
• Add README.md with scope statement
• Add .gitignore for secrets/build artifacts
• If CI/automation needed: register deploy key or token
• Document in Iron-Legion/documentation fleet registry

---

7. Open Questions

1. Should we create a Gitea org-level default branch protection template? (Applies to all new repos automatically)
2. Should F.R.I.D.A.Y. also store the R/W token? (Currently only Artemis has it in fleet.env)
3. Do we want a CODEOWNERS file in each repo to auto-assign reviewers?

---

8. Fleet Credential Store Update

⚠️ Status: Tokens documented here are EXPIRED / REVOKED (confirmed 2026-06-05 via 401 on Gitea API). Action required: Generate new tokens via Gitea UI → User Settings → Applications → Generate New Token. Updated token values should be written to ~/.ansible/secrets/deploy_token and ~/.hermes/credentials/fleet.env.

Original values (for reference — DO NOT USE):

GITEA_DEPLOY_TOKEN=226c3ef38eb35914ae6b647803c2e597f66f28cb  # EXPIRED
GITEA_RW_TOKEN=968e86d51ab9b6b2a3eb5e97b391ce8c6534ec2d      # EXPIRED

Source of truth: /home/jarvis/.ansible/secrets/deploy_token (must be updated with new tokens).