146 lines
5.5 KiB
Markdown
146 lines
5.5 KiB
Markdown
# 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):
|
|
```bash
|
|
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
|
|
|
|
Added to `~/.hermes/credentials/fleet.env`:
|
|
```
|
|
GITEA_DEPLOY_TOKEN=226c3ef38eb35914ae6b647803c2e597f66f28cb
|
|
GITEA_RW_TOKEN=968e86d51ab9b6b2a3eb5e97b391ce8c6534ec2d
|
|
```
|
|
|
|
Source of truth remains `/home/jarvis/.ansible/secrets/deploy_token`.
|