forgejo-process-mcp

MCP server that turns Forgejo CI/CD into an async, agent-native process: git mechanics, PRs, and CI/CD runs as tools — with cicd_start returning immediately so the agent keeps developing, and run outcomes delivered later as events (ci_run_failed / ci_run_succeeded / deploy_finished) via cicd_events.

Built for the pattern: "when Forgejo accepts the CI/CD start, tell the agent it can continue development — and notify it when something fails or a deploy finishes, so production Playwright testing can start."

Pairs with the delivery-loop skill (skills/delivery-loop/SKILL.md): the skill owns judgment and sequencing, this server owns mechanics.

Tools

Related MCP server: project-tasks-mcp

How the async flow works

agent ──cicd_start──▶ MCP: commit+push, register watch ──▶ returns at once:
                      "accepted — you can continue development"
                      │
background watcher (polls Forgejo Actions, default 15 s)
                      │
        run reaches terminal state ──▶ event queued
                      │
agent ──cicd_events──▶ {ci_run_failed | ci_run_succeeded | deploy_finished}

Watches persist on disk ($STATE_DIR/watches.json), so a restarted server resumes watching. An optional webhook listener (FORGEJO_MCP_WEBHOOK_PORT) accepts Forgejo webhooks for instant events — from a dockerized Forgejo use http://host.docker.internal:<port>/webhook.

Setup

npm install
npm run build

Configuration via environment:

Register with an MCP host (example: kimi-code config.toml)

[mcp.servers.forgejo-process]
command = "node"
args = ["/abs/path/forgejo-process-mcp/dist/index.js"]
env = { FORGEJO_URL = "http://127.0.0.1:3310", FORGEJO_TOKEN = "..." }

Forgejo instance notes (found during bring-up, Forgejo 11.0.16)

1. Runner capacity starves CI. With capacity: 1 in the runner's config.yml, one chatty repo floods the FIFO queue and other repos' runs wait for hours. Raise capacity (this instance: 4).

2. Webhooks need an allowlist. Default webhook.ALLOWED_HOST_LIST blocks host.docker.internal, so a dockerized Forgejo cannot call a webhook listener on the host. Add it to app.ini: [webhook] ALLOWED_HOST_LIST = host.docker.internal,...

3. Run planning lag is minutes, not seconds. New runs sit in an initial state before jobs are planned and contexts appear. This server therefore watches commit statuses (durable) rather than /actions/tasks (entries vanish after completion), and declares green only after the context set is stable across two polls.

4. No run-level REST API in Forgejo 11 (/actions/runs is 404) — commit statuses per pushed SHA are the reliable read.

End-to-end test

Drives a real failure-then-success cycle against a live Forgejo (clone → failing CI → ci_run_failed event → fix → ci_run_succeeded):

node scripts/e2e.mjs

License

MIT