Forgejo Workflow
by @nerasse
Forgejo via fj and REST API for repos, issues, PRs, wiki, CI, and reviews.
Required binaries:
fjcurljqgitCreate an application token from:
$FORGEJO_URL/user/settings/applications
Request only the scopes needed for the task. Common patterns for this skill are:
read:repository or write:repository for repositories, pull requests, wiki, and releasesread:issue or write:issue for issues, labels, and milestonesread:notification or write:notification for notificationsread:organization or write:organization for org labels and teamsread:user or write:user only if user-level endpoints are neededFORGEJO_URL must be the Forgejo base URL such as
https://, not an /api/v1 endpoint.
FORGEJO_URL is the target Forgejo instance URL, not this skill repository URL.
| Symptom | Likely cause | Action |
|---|---|---|
| FORGEJO_URL is not set | Required instance URL missing | Export FORGEJO_URL before running fj or REST workflows |
| FORGEJO_TOKEN is not set | Required application token missing | Create a token in Forgejo and export FORGEJO_TOKEN |
| fj: command not found | forgejo-cli is not installed | Install fj with the supported metadata installer or another package source |
| curl: command not found or jq: command not found | REST fallback tools are missing | Install the missing system tools before using REST workflows |
| git: command not found | Local review and diff workflows are unavailable | Install git before using review flows |
| fj auth add-key fails | fj needs both a username and a resolvable target host | Run fj auth add-key in a configured repo or fj --host |
| fj is not authenticated for the target host | REST may work, but CLI commands will fail | Run fj auth list to inspect configured hosts, then add the key for the target host |
| repo not found | Wrong owner or repo, wrong instance, or missing access | Verify owner/repo, the target instance, and token permissions |
| cannot infer repository | No local git remote and no explicit repo selection | Ask the user for owner/repo, and include --host or a host-qualified target when needed |
| HTTP 401 or HTTP 403 | Invalid token or insufficient scope | Verify token validity, scopes, and repo permissions |
| HTTP 404 from the API | Wrong path or endpoint unsupported on this Forgejo version | Recheck the URL and confirm support in $FORGEJO_URL/api/swagger |
| fj lacks the requested operation | CLI gap compared to Forgejo API | Fall back to curl and jq using the REST API |
clawhub install forgejo-fj-api