MF-9: Multi-forge runbook + docs #300

New issue

code-lead · 2026-04-23T23:33:17Z

code-lead commented

2026-04-23 23:33:17 +00:00

As an operator, I want an end-to-end runbook for "how to add a GitHub / GitLab repo to the fleet" so that onboarding a new forge-hosted repo doesn't require reading the code.

Acceptance criteria

Runbook doc

New docs/multi-forge.md with one runbook per forge:
1. Create the webhook in the forge UI (exact events, URL, secret format).
2. Create a PAT with the required scopes (see below).
3. Drop the token file at the path declared in config/agents.json.
4. Add the repo to config/agents.json with forge: "<type>".
5. Verify dispatch with a smoke-test issue.

Per-forge scope checklist

GitHub: repo, workflow.
GitLab: api (broadest; GitLab doesn't split).
Forgejo: repo, write:issue, write:repository.

Top-level docs

README "Forges supported" section lists all three with links to their runbooks.
CLAUDE.md "Multi-repo" section updated to reference the new doc.
docs/multi-repo.md (existing) cross-links to docs/multi-forge.md where relevant.

Verification hooks in the runbook

A final "smoke test" section explains the one just recipe or curl command that proves the webhook path, adapter selection, and token file all line up.

Out of scope

Operator UI for adding a repo. Stays CLI + config file for now.
Automated webhook creation via the forge API. Manual in the runbook.
Screenshots per forge (UIs drift — text instructions age better).

References

Spec: specs/multi-forge.md § MF-9.
docs/multi-repo.md — existing multi-repo doc to cross-link.
CLAUDE.md — top-level index.

Dependencies

Blocks on MF-1 and MF-2 — the runbook needs the GitHub and GitLab adapters live so the smoke-test steps actually work.
Blocks on MF-4 implicitly (via MF-1 / MF-2). No direct edge.

Depends on #292 (MF-1)
Depends on #293 (MF-2)

As an operator, I want an end-to-end runbook for "how to add a GitHub / GitLab repo to the fleet" so that onboarding a new forge-hosted repo doesn't require reading the code. ## Acceptance criteria ### Runbook doc - [ ] New `docs/multi-forge.md` with one runbook per forge: 1. Create the webhook in the forge UI (exact events, URL, secret format). 2. Create a PAT with the required scopes (see below). 3. Drop the token file at the path declared in `config/agents.json`. 4. Add the repo to `config/agents.json` with `forge: "<type>"`. 5. Verify dispatch with a smoke-test issue. ### Per-forge scope checklist - [ ] GitHub: `repo`, `workflow`. - [ ] GitLab: `api` (broadest; GitLab doesn't split). - [ ] Forgejo: `repo`, `write:issue`, `write:repository`. ### Top-level docs - [ ] README "Forges supported" section lists all three with links to their runbooks. - [ ] CLAUDE.md "Multi-repo" section updated to reference the new doc. - [ ] `docs/multi-repo.md` (existing) cross-links to `docs/multi-forge.md` where relevant. ### Verification hooks in the runbook - [ ] A final "smoke test" section explains the one `just` recipe or `curl` command that proves the webhook path, adapter selection, and token file all line up. ## Out of scope - Operator UI for adding a repo. Stays CLI + config file for now. - Automated webhook creation via the forge API. Manual in the runbook. - Screenshots per forge (UIs drift — text instructions age better). ## References - Spec: [`specs/multi-forge.md`](../src/branch/main/specs/multi-forge.md) § MF-9. - `docs/multi-repo.md` — existing multi-repo doc to cross-link. - CLAUDE.md — top-level index. ## Dependencies - **Blocks on MF-1** and **MF-2** — the runbook needs the GitHub and GitLab adapters live so the smoke-test steps actually work. - **Blocks on MF-4** implicitly (via MF-1 / MF-2). No direct edge.  - Depends on #292 (MF-1) - Depends on #293 (MF-2)

code-lead added the

area:security

area:meta

type:user-story

labels

2026-04-23 23:33:18 +00:00

dev was assigned by code-lead

2026-04-23 23:33:18 +00:00

code-lead referenced this issue

2026-04-23 23:34:47 +00:00

Tracking: multi-forge spec breakdown (Forgejo + GitHub + GitLab behind ForgePort) #291

charles referenced this issue from a commit