- Go 99.6%
- Makefile 0.4%
|
|
||
|---|---|---|
| cmd/fgj | ||
| internal | ||
| .gitignore | ||
| AGENTS.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| mise.toml | ||
| README.md | ||
fgj — a CLI for self-hosted Forgejo
this was entirely vibe-coded with Opus 5.5 - use with caution
fgj talks to your Forgejo instance over the Forgejo REST API (/api/v1). It can:
- create repositories (personal or in an organisation)
- open, list and merge pull requests, using your local git checkout to fill in the defaults
It targets the current Forgejo LTS release, v15. Every request field it sends exists in the v15 API
schema. Older servers still work for basic use, and fgj auth login warns you when the server is older
than v15.
Install
go install git.markow.dev/daniel/Forgejo-CLI/cmd/fgj@latest
If the repository is private, first set GOPRIVATE=git.markow.dev and make sure git can authenticate to
the server.
To build from a checkout, use mise to install the pinned Go toolchain:
mise install # installs the Go version from mise.toml
make build # -> bin/fgj
make install # -> $(go env GOPATH)/bin/fgj
Without mise, you need Go 1.26 or newer.
Authenticate
Create an access token in Forgejo under Settings → Applications. These are the scopes Forgejo v15
requires (from routers/api/v1/api.go):
| scope | needed for |
|---|---|
read:user |
always: auth login / auth status identify the token owner |
write:repository |
pr create, pr merge; also repo create for personal repositories |
read:repository |
pr list (included in write:repository) |
write:user |
repo create for personal repositories (with write:repository) |
write:organization |
repo create ORG/NAME |
read:issue |
--label / --milestone on pr create and pr list |
read:organization |
--label with organisation-wide labels (optional) |
If a command fails with 403 token does not have at least one of required scope(s): [...], the
message names the missing scope. Create a token that includes it and run fgj auth login again.
fgj auth login --url https://git.example.com # prompts for the token (hidden input)
echo "$TOKEN" | fgj auth login --url git.example.com --with-token
fgj auth status # lists hosts and re-checks each token
fgj auth logout git.example.com
You can save several instances. The first one you log in to becomes the default; pass --default to change it.
Credentials are stored in ~/.config/fgj/config.json with mode 0600. Set FGJ_CONFIG to use a different path.
Choosing the instance
For each command, fgj picks the instance in this order:
--host(a saved host name such asgit.example.com, or a URL)$FORGEJO_URL- the saved host whose hostname matches the current git remote
- the default saved host
--token or $FORGEJO_TOKEN overrides the saved token. In CI you can skip auth login entirely:
FORGEJO_URL=https://git.example.com FORGEJO_TOKEN=... fgj repo create build-cache
Instances served under a sub-path, such as https://example.com/forgejo, are supported.
Create a repository
fgj repo create my-tool -d "A small tool" # private, empty
fgj repo create my-tool --init --license MIT --gitignores Go # with an initial commit
fgj repo create acme/service --public # in organisation "acme"
fgj repo create scratch --object-format sha256 --default-branch trunk
fgj repo create my-tool --json # machine-readable output
Repositories are private by default. --license, --gitignores, --readme and --issue-labels name
templates that ship with your instance, and any of them implies --init. Run fgj repo create --help
to see every flag (--template, --trust-model, …).
Create a pull request
From inside a checkout whose origin points at the Forgejo instance:
git push -u origin my-feature
fgj pr create --fill # title and body come from the last commit
fgj pr create -t "Add retries" -b "Fixes #12" -l bug -l backend -a alice -m v1.2
Defaults:
- repository: parsed from
--remote(defaultorigin). HTTPS,ssh://and scp-style URLs all work. - head: the current branch
- base: the repository's default branch
Outside a checkout, or to target a different repository:
fgj pr create -R acme/api -H my-feature -B main -t "Title" -F description.md
fgj pr create -R upstream/proj -H myfork:fix-typo -t "Fix typo" # PR from a fork
git log -1 --format=%b | fgj pr create -t "Title" -F - # body from stdin
--label accepts label names (case-insensitive). It looks in the repository's labels first, then the
organisation's. --milestone accepts a milestone name or ID, and --due takes YYYY-MM-DD
or RFC 3339.
List pull requests
fgj pr list # open PRs of the repository in the current checkout
fgj pr list --state merged --limit 10 # states: open (default), closed, merged, all
fgj pr list -R acme/api --author alice --label bug --milestone v1.2
fgj pr list --sort recentupdate --json
--label can be repeated, and a PR must have all the given labels to be listed. --limit defaults to 30;
--limit 0 lists everything. The API has no "merged" state, so --state merged fetches closed PRs and
keeps the merged ones.
Merge a pull request
fgj pr merge 12 # repository's default merge style
fgj pr merge # the open PR whose head is the current branch
fgj pr merge 12 --style squash --delete-branch -t "Add retries (#12)"
fgj pr merge 12 --auto # merge once required checks pass
fgj pr merge 12 --cancel-auto
--styleis one ofmerge,rebase,rebase-merge,squashorfast-forward-only. It defaults to the repository's default style. Styles the repository doesn't allow are rejected before anything is sent.--delete-branchdefaults to the repository's "delete branch after merge" setting. Use--delete-branch=falseto keep the branch anyway.- Safety:
fgjsends the head commit it looked at, so if someone pushes to the branch in the meantime the merge fails withhead out of dateinstead of merging commits you haven't seen. In an interactive terminal it asks for confirmation first.--yesskips that, and scripts (no terminal) are never prompted. --autoasks Forgejo to merge once all required status checks have passed. If they already have, it merges straight away.
Development
mise install
make test # unit and end-to-end tests (needs git on PATH)
make vet
The end-to-end tests in internal/cmd run the real command tree against an in-process fake Forgejo
server. That server rejects any request field missing from the Forgejo v15 swagger schema, so these
tests catch requests the LTS API would not understand.
Layout:
cmd/fgj/ entry point (main package)
internal/cmd/ cobra commands (auth, repo, pr)
internal/forgejo/ minimal typed API client
internal/config/ saved hosts and tokens
internal/gitutil/ reads remotes, branches and commits from the local checkout
License
MIT. See LICENSE.