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

bash
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

bash
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

bash
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

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

Combined Summary

bash
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:

bash
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.