# GITEA.md Gitea is the source of truth for code, documentation, ADRs, and architecture (see `COMPANY.md`). Gitea and ACT Runner (Linux and macOS runners) are deployed and reachable today — this document governs how every AI employee actually uses them. ## Instance - URL: `` - Organization: `` - Every project lives in its own repository under this organization, matching a folder in `projects/` in this repo (the operating-system repo and individual project repos are intentionally separate — see `projects/README.md`). ## Identity Every AI employee has its own Gitea account, SSH key, and Git identity — never a shared token (`COMPANY.md`, `ORGANIZATION.md`). Convention for accounts: ``` @.local ``` e.g. `backend1@.local`, `qa1@.local`. The `` suffix exists so the company can run more than one instance of a role concurrently (e.g. `backend1`, `backend2`) without identity collisions. Git commit author/email must match the employee's own identity — never another role's, and never the Founder's. ## Branch naming ``` /- ``` e.g. `backend1/LOC-142-upload-api`, `qa1/LOC-142-upload-api-fix`. The `` is the Plane task identifier — this is what makes commit-to-task linkage automatic and auditable (see `PLANE.md` on why identity + linkage replaces the need for a custom dashboard). - `main` is always deployable. Nothing is pushed to `main` directly, including by the Architect or DevOps — everything arrives via reviewed PR. - Long-lived feature branches are avoided; if a branch outlives its Task's sprint, that's a signal for the Project Manager to check in on it, not to let it drift. ## Commit messages ``` (): Task: ``` `` follows conventional commit types (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`). The `Task:` trailer is required — it's what ties the commit back to Plane. A commit without a linked task is only acceptable for repo-level housekeeping that isn't tracked work. ## Pull requests - Every PR must link its Plane Task in the description. - PR description states what changed and why, not just what — the diff already shows what. - No PR merges without: (1) at least one review approval from the Architect or a peer engineer per `WORKFLOW.md`, (2) a passing ACT Runner run (`ACT_RUNNER.md`), and (3) no unresolved `security-hold` label from the Security Engineer. - QA verification happens after merge-readiness is otherwise established, per the task lifecycle in `WORKFLOW.md` — QA is a gate on the Task closing, not a blocker on the PR merging, unless a project's `PROJECT.md` says otherwise. - The engineer who opened the PR does not merge their own work — merging is the reviewer's action once approval and CI are both green. ## Signing Commits should be signed with the employee's own SSH key wherever Gitea's configuration supports it. An unsigned commit from an identity that has a registered signing key is treated the same as a review red flag — investigate before trusting it. ## Reviews Review etiquette is defined in `EMPLOYEE_HANDBOOK.md`. Mechanically: - The Architect reviews anything with architectural impact; routine within-scope PRs may be reviewed by a peer engineer in the same discipline. - Security-sensitive changes (auth, secrets, dependencies, containers — see `SECURITY.md`) always get a Security Engineer review in addition to the standard review. - A rejected review returns the PR to the author with specific, actionable comments — see `EMPLOYEE_HANDBOOK.md` on what a real review looks like. ## Permissions - Engineering roles: write access to their assigned project repositories, no admin/settings access. - Architect: write + branch protection configuration on repos they're actively designing for. - DevOps: admin access scoped to CI/CD configuration (`.gitea/workflows`, ACT Runner settings) across all project repos. - Security: read access everywhere, write access to security-relevant configuration (`SECURITY.md` policy enforcement), and the standing ability to attach a `security-hold`. - Project Manager: no code write access required — Plane is their instrument, not Gitea commits. - This document (`Local-LLC` repo itself): the Documentation Engineer and Architect have write access for policy changes; role-defining or organization-defining changes still route through the Founder per `FOUNDER.md`.