Forgejo API

A digest of the Forgejo v17 API (/api/v1), meant for curl + jq. Work from this file; for anything it leaves out, see When this file is not enough.

Setup

• Instance (FORGEJO_URL): take the host from git remote get-url origin (git@host:owner/repo.git, ssh://git@host[:port]/owner/repo.git or https://host/owner/repo.git) and set FORGEJO_URL=https://<host>, without the SSH port; OWNER/REPO come from the same path. If there is no remote, or it is not Forgejo (GET https://<host>/api/v1/version fails), keep the user's exported FORGEJO_URL. If neither works, stop and ask the user for the instance URL.

• Token: read FORGEJO_TOKEN. If it is unset, stop and tell the user to create one under Settings → Applications → Generate New Token and export it as FORGEJO_TOKEN. Scopes are read:/write: per area (repository covers Actions, issue, organization, user, …); a 403 with a valid token means a missing scope, so name the scope the call needs.

• Request template:

  API="$FORGEJO_URL/api/v1"
  curl -sS --fail-with-body -H "Authorization: token $FORGEJO_TOKEN" "$API/repos/$OWNER/$REPO" | jq .
  # with a JSON body
  curl -sS --fail-with-body -H "Authorization: token $FORGEJO_TOKEN" -H 'Content-Type: application/json' \
    -X POST "$API/repos/$OWNER/$REPO/issues" -d "$(jq -n --arg t "$TITLE" --arg b "$BODY" '{title:$t, body:$b}')"
  

  Build bodies with jq -n --arg, so quotes and newlines in Markdown survive.