| name | forgejo |
| description | Forgejo REST API toolkit — manage issues, pull requests, wikis, and repos on a Forgejo server. Use when the agent needs to file an issue, open / review / merge a PR, read or write a wiki page, or look up repo / branch info. One standalone script per resource type. Reads credentials from environment, `~/.skillhone/settings.json`, or `_data/forgejo_config.txt`.
|
| compatibility | Requires Python 3.10+ and network access to a Forgejo instance. |
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):
- Environment variables:
FORGEJO_URL, FORGEJO_TOKEN, FORGEJO_OWNER, FORGEJO_REPO
~/.skillhone/settings.json + ~/.skillhone/identities.conf_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
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.
