Forgejo

Forgejo

Thin wrapper around the Forgejo REST API. Each resource lives in its own script so the agent can discover and invoke them individually. SkillHone depends on this as a VCS backend skill, but it stays independent so another backend such as GitLab or Gitea can provide the same workflow surface.

Scripts

Script	Resource	Representative usage
scripts/issue.py	Issues	python3 scripts/issue.py create --title "Bug"
scripts/pr.py	Pull requests	python3 scripts/pr.py merge 1
scripts/wiki.py	Wiki pages	python3 scripts/wiki.py get --title "Analysis"
scripts/repo.py	Repo metadata	python3 scripts/repo.py branches
scripts/summary.py	Aggregate dashboard	python3 scripts/summary.py

Every script supports --help. Run it before guessing flags.

Configuration

Resolved in this order (first match wins):

1. Environment variables: FORGEJO_URL, FORGEJO_TOKEN, FORGEJO_OWNER, FORGEJO_REPO
2. ~/.skillhone/settings.json + ~/.skillhone/identities.conf
3. _data/forgejo_config.txt in the current working directory

If nothing is set, the script exits with a clear message naming the missing variable.

Usage By Resource

Issues

python3 scripts/issue.py list
python3 scripts/issue.py view <N>
python3 scripts/issue.py create --title "Fix: timeout" --body "## Problem\n..."
python3 scripts/issue.py close <N>
python3 scripts/issue.py comment <N> --body "Done"

Pull Requests

python3 scripts/pr.py list
python3 scripts/pr.py view <M>
python3 scripts/pr.py create --title "Fix timeout" --head fix/timeout --base main --body "Closes #1"
python3 scripts/pr.py review <M> --approve
python3 scripts/pr.py merge <M> --method merge
python3 scripts/pr.py comment <M> --body "LGTM"

Wiki

python3 scripts/wiki.py list
python3 scripts/wiki.py get --title "Iteration-1-Observation"
python3 scripts/wiki.py create --title "Page" --body "content"
python3 scripts/wiki.py edit --title "Page" --body "updated content"

Repo Metadata

python3 scripts/repo.py info
python3 scripts/repo.py branches

Combined Summary

python3 scripts/summary.py
# open issues + open PRs + latest observation wiki page

Invocation From Other Skills

Other skills living under ~/.skillhone/skills/ call these scripts via their absolute path:

python3 ~/.skillhone/skills/forgejo/scripts/issue.py list

This keeps the VCS backend replaceable. A GitLab or Gitea skill can expose an equivalent command surface without changing SkillHone's optimization logic.

Gotchas

• Tokens with @ characters break git clone URL injection. Use a token without @ or URL-encode it.
• merge --method squash is not supported by older Forgejo versions. If you hit Unknown method, fall back to merge.
• Wiki pages are stored as .md files in a separate git repo (<repo>.wiki.git). wiki.py hides that, but if you need custom editing, clone the wiki repo directly.

Hard Rules

• Never print the Forgejo token to stdout/stderr logs. The scripts already redact; don't paste it into --body fields.
• Do not call Forgejo's REST API directly with curl or handcrafted HTTP from SkillHone workflows. Use these backend scripts so credential loading, redaction, and backend replacement stay centralized.
• Do not cat _data/forgejo_config.txt, ~/.skillhone/settings.json, or identities.conf to discover credentials. The scripts resolve credentials internally.
• Do not push directly to main via any of these scripts. PRs only.
• When you get a 401/403, re-check the config resolution order above before changing the script.