Skip to content

Forgejo — Reference

  • Website: https://forgejo.org
  • API docs (Swagger): https://git.eva-00.network/swagger
  • CLI docs: https://forgejo.org/docs/next/admin/command-line/
  • Token scopes: https://forgejo.org/docs/next/user/token-scope/
  • Actions guide: https://forgejo.org/docs/latest/user/actions/
  • GitHub: https://github.com/forgejo/forgejo
  • Runner: https://code.forgejo.org/forgejo/runner

Authentication

API requests use a personal access token in the Authorization header or ?token= query parameter.

# Header auth (preferred)
curl -s -H "Authorization: token $FORGEJO_TOKEN" https://git.eva-00.network/api/v1/...

# Query param auth
curl -s "https://git.eva-00.network/api/v1/...?token=$FORGEJO_TOKEN"

Token for the claude bot account is stored in Vault at secret/forgejo → claude_mcp_access_token.

API — Repositories

List repos for a user

curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  https://git.eva-00.network/api/v1/repos/search?owner=holo | python3 -c \
  "import json,sys; [print(r['name']) for r in json.load(sys.stdin)['data']]"

Get repo details

curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2

List branches

curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/branches

Get file contents

curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/contents/ansible/playbooks/caddy.yml

Response includes content (base64-encoded).

Create or update a file

# Get existing SHA first
SHA=$(curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/contents/path/to/file | python3 -c \
  "import json,sys; print(json.load(sys.stdin)['sha'])")

curl -s -X PUT -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/contents/path/to/file \
  -d "{\"message\": \"update file\", \"content\": \"$(echo -n 'file contents' | base64)\", \"sha\": \"$SHA\"}"

API — Actions (Workflows)

Trigger a workflow manually

curl -s -X POST -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/actions/workflows/caddy.yml/dispatches \
  -d '{"ref": "main"}'

Trigger with inputs

curl -s -X POST -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/actions/workflows/vault-write.yml/dispatches \
  -d '{"ref": "main", "inputs": {"path": "myservice", "data": "{\"key\": \"value\"}"}}'

List recent workflow runs

curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  "https://git.eva-00.network/api/v1/repos/holo/chizuru-v2/actions/tasks?limit=10" | python3 -c \
  "import json,sys; [print(f'{t[\"id\"]} {t[\"status\"]} {t[\"name\"]}') for t in json.load(sys.stdin)['workflow_runs']]"

CLI — Admin Commands

Run from inside LXC 100 (ssh [email protected] "pct exec 100 -- ..." or ssh [email protected]).

# Auth source management (OIDC)
forgejo admin auth add-oauth --name pocketid --provider openidConnect \
  --key <client_id> --secret <client_secret> \
  --auto-discover-url https://auth.eva-00.network/.well-known/openid-configuration

forgejo admin auth update-oauth --id <auth_id> --secret <new_secret>
forgejo admin auth list

# User management
forgejo admin user list
forgejo admin user create --username claude --email [email protected] --password <pass>
forgejo admin user change-password --username holo --password <new_pass>

# Repository management
forgejo dump   # full backup (DB + repos + config)

CLI — Runner Commands

Run from LXC 101 (ssh [email protected]).

# Status
rc-service forgejo-runner status

# Register (one-time)
forgejo-runner register --instance https://git.eva-00.network \
  --token <registration_token> --name runner-01

# Config location
cat /root/.runner

What the API/CLI Cannot Do

Gap Workaround
Cannot read workflow step logs via API Query Loki: {job="forgejo-actions", task_id="<id>"} or decompress .log.zst via SSH
Cannot cancel a running workflow via API Use the Forgejo web UI
Cannot manage Actions secrets via API Set secrets through the Forgejo web UI (Settings → Secrets)
Cannot view runner registration tokens via API Generate from web UI: Site Administration → Actions → Runners
No API for managing webhook delivery history Check via web UI: Repo → Settings → Webhooks → Recent Deliveries
forgejo admin CLI only works on LXC 100 (Alpine) No remote CLI — must SSH into the LXC
Actions log shipping has ~2 min delay Compressed .log.zst files are pushed to Loki on a cron schedule