From c6e97ef600f691f66e694bf97eb50d1b46301cce Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 4 Jul 2026 17:45:40 +0200 Subject: [PATCH] docs(forge-tools): clarify create_repo MCP tool vs repo-create CLI Agents cannot create repos directly via their forge token (no Create scope; push-to-create disabled). Document the two paths: - mcp__hyperhive__create_repo (forge tool group): creates under agents/ org via hive-c0re, adds write-collaborator access, enables branch protection. The standard agent path. - hive-forge repo-create / repo-add-collaborator (CLI): use the agent's own token; repo lands under agent's user account or org. --- docs/tools/forge.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/tools/forge.md b/docs/tools/forge.md index 605182da..1245239a 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -178,9 +178,20 @@ plain comment show under `last comment`, not `reviews`. ### Repo management -Three verbs create repos and manage their membership — the supported -path for workflows that need a fresh repo (agents cannot push to -non-existent repos; the Forgejo instance disables push-to-create). +Agents **cannot create repos directly via forge token** — Forgejo +disables push-to-create and the agent token doesn't have the Create +scope. Two paths exist depending on where the repo should live: + +**Agent repos (`agents/`)** — Use the `mcp__hyperhive__create_repo` +MCP tool (requires the `forge` tool group). hive-c0re creates the repo in +the c0re-owned `agents/` org, adds you as a write collaborator (not +owner), and enables branch protection (operator-team merge approval +required — you cannot self-merge). Clone URL is returned immediately. +This is the standard path for agents that need a working repo. + +**Other repos** — Use the CLI verbs below (`repo-create` / `repo-add-collaborator`). +These use the agent's own forge token so the repo lands under the agent's +user account or an org the agent belongs to. **`repo-create `** — create a repo under the authenticated user and print its URL. Key flags: @@ -195,8 +206,7 @@ and print its URL. Key flags: active repo (`-r`/`HIVE_FORGE_REPO`). Companion to `repo-create`. The `--permission` flag accepts `read` / `write` (default) / `admin`. `hive-c0re` uses this internally when an agent's config repo is -initialised (`create_repo` → `repo-add-collaborator` → agent gets -write access). +initialised. **`repo-labels [PATTERN]`** — list every label defined on the repo, optionally filtered by a name substring (case-sensitive). Distinct from