Forgejo Workflow

Use the fj CLI and the Forgejo REST API to interact with Forgejo repositories, issues, pull requests, wiki pages, CI, and code review workflows.

Overview#

Use this skill when:

• Creating, listing, viewing, editing, or closing issues
• Creating, checking out, merging, or reviewing pull requests
• Managing repositories, forks, releases, labels, and milestones
• Reading or writing wiki pages
• Inspecting Forgejo Actions or CI status
• Performing a structured code review on a Forgejo pull request

Do not use this skill when:

• Working on local-only git operations such as commit, rebase, stash, push, or branch cleanup
• Working with GitHub or GitLab instead of Forgejo
• Performing Forgejo server administration that requires the forgejo server CLI

This skill targets one active Forgejo instance at a time.

Prefer fj for supported operations, use the REST API for feature gaps, and use local git only for review and diff workflows.

Prerequisites#

Required binaries:

• fj
• curl
• jq
• git

Create an application token from:

text

$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 releases
• read:issue or write:issue for issues, labels, and milestones
• read:notification or write:notification for notifications
• read:organization or write:organization for org labels and teams
• read:user or write:user only if user-level endpoints are needed

FORGEJO_URL must be the Forgejo base URL such as https://<your-forgejo-host>, not an /api/v1 endpoint.

FORGEJO_URL is the target Forgejo instance URL, not this skill repository URL.

Required environment#

VariableRequiredExamplePurposeFORGEJO_URLYeshttps://<your-forgejo-host>Base URL of the target Forgejo instance for this skill's REST and instance-selection workflowFORGEJO_TOKENYesforgejo_pat_...Application token used by this skill's REST examples and recommended for fj setup

Authenticate fj with the same token when the target host is already inferable from the current repository context:

text

fj auth add-key <username>

If the current directory is not a Forgejo repository, or if you need to target a different instance explicitly, pass the host:

text

fj --host <forgejo-host> auth add-key <username>

The examples in this skill use the same token for REST API calls:

text

curl -sS \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "$FORGEJO_URL/api/v1/..."

If FORGEJO_URL or FORGEJO_TOKEN is missing, stop and ask the user to provide the missing value instead of guessing.

REST-ready requires FORGEJO_URL and FORGEJO_TOKEN. fj-ready also requires fj auth for the target host.

Readiness check#

Before doing Forgejo work, verify the required tools, env, and auth state.

Check binaries:

text

command -v fj curl jq git

Check required env vars:

text

test -n "$FORGEJO_URL" && test -n "$FORGEJO_TOKEN"

Check fj auth for the target host:

text

fj auth list

If any readiness check fails, stop and ask for the missing install, env value, or fj auth setup before proceeding.

Repository resolution#

Resolve the target repository in this order:

1. Explicit repository selection when the command supports it, such as --repo owner/repo
2. The current repository context as resolved from the available git remotes
3. Ask the user for owner/repo

Do not guess the repository from issue or pull request numbers alone.

For many issue and pull-request commands outside a local clone, explicit target selection is done with embedded forms such as owner/repo#42 rather than a separate --repo flag.

forgejo-cli does not hardcode origin here. In practice it can resolve from a sole remote, the current branch upstream remote, an explicit --remote, or a remote matching --host.

Use FORGEJO_URL as the source of truth for REST calls. Use fj --host when the current repository context does not already point at the target instance. fj itself does not read FORGEJO_URL.

Tool priority#

1. fj CLI for all supported Forgejo operations
2. curl plus jq for Forgejo API gaps
3. git for diff, log, merge-base, and blame during code review

Always prefer fj over raw API calls when both can do the job.

Unless noted otherwise, the examples below assume the host and repository are already resolved from repo context, --host, --repo, or an embedded target.

Repository operations#

text

fj repo view owner/repo
fj repo create my-repo --private --description "..."
fj repo clone owner/repo
fj repo fork owner/repo
fj repo delete owner/repo
fj repo readme owner/repo
fj repo browse owner/repo
fj repo migrate <URL> name --service forgejo --include wiki,releases,issues --token

When using --include values such as wiki, releases, or issues, specify a non- git migration service such as forgejo. The --token flag is interactive and should not be documented as --token <value>.

There is no generic fj repo list command in forgejo-cli. To list repositories, use user or organization commands such as:

text

fj user repos
fj user repos username
fj org repo list my-org

When not inside the target repository, prefer explicit repository selection when the command supports it:

text

fj <command> --repo owner/repo

For issue and pull-request commands that do not support --repo, use an embedded target such as owner/repo#42.

Issues#

text

fj issue search
fj issue create "Bug: ..." --body "..."
fj issue view 42
fj issue edit 42 title "New title"
fj issue comment 42 "My comment"
fj issue close 42

If the repository uses issue templates, issue creation may require --template or --no-template.

Pull requests#

text

fj pr search
fj pr create "feat: ..." --body "..."
fj pr create --agit "..."
fj pr view 55
fj pr checkout 55
fj pr status 55
fj pr merge 55 --method rebase --delete
fj pr close 55
fj pr comment 55 "LGTM"
fj pr edit 55 labels --add bug --rm wip

Some PR commands can infer the PR number from the current branch, but fj pr checkout still requires an explicit PR number.

fj pr create --agit is a specialized local-git workflow that pushes HEAD:refs/for/<base> and may prompt to write git config.

Before checking out a pull request locally, inspect the current worktree:

text

git status --porcelain

If the worktree is dirty, warn the user before running fj pr checkout.

fj pr checkout will fail if there are uncommitted changes.

Releases#

text

fj release list
fj release create 0.1.0 --tag 0.1.0

Organizations and teams#

text

fj org list
fj org view my-org
fj org label list my-org
fj org label add my-org "bug" "#d73a4a"
fj org team list my-org
fj org team member add my-org devs username

Wiki#

Read wiki pages with fj:

text

fj wiki --repo owner/repo view "Page Name"

List wiki pages with fj:

text

fj wiki --repo owner/repo contents

Use the REST API for wiki writes, updates, and deletes. See references/api-cheatsheet.md.

Labels and milestones#

Use fj for organization labels. Repository labels are available under fj repo labels on current forgejo-cli source builds, but not in packaged v0.4.0 and v0.4.1 releases.

Use the REST API for milestones, and as the fallback whenever the local fj build does not expose the needed label operation. See references/api-cheatsheet.md.

CI and Forgejo Actions#

Use fj for the quick status path:

text

fj --repo owner/repo actions tasks
fj pr status 55

Use the REST API when detailed run information is needed. See references/ci-actions.md.

Code review#

When asked to review a pull request, follow references/code-review.md.

Short version:

1. Inspect worktree state before checkout.
2. Check out the pull request with fj pr checkout <number>.
3. Determine the actual base branch from the pull request metadata.
4. Compute the merge base against that base branch.
5. Review the diff using the criteria in references/code-review.md.
6. Post a comment with findings.
7. Approve only if the user explicitly asks for approval.
8. Merge only if the user explicitly asks for merge.

Keep approval and merge as separate actions.

Pagination#

Many Forgejo API endpoints support ?page=<n>&limit=<n>.

When fetching large result sets, keep paging until the response shape or available pagination metadata indicates there are no more results.

Troubleshooting#

SymptomLikely causeActionFORGEJO_URL is not setRequired instance URL missingExport FORGEJO_URL before running fj or REST workflowsFORGEJO_TOKEN is not setRequired application token missingCreate a token in Forgejo and export FORGEJO_TOKEN``fj: command not found``forgejo-cli is not installedInstall fj with the supported metadata installer or another package sourcecurl: command not found or jq: command not foundREST fallback tools are missingInstall the missing system tools before using REST workflowsgit: command not foundLocal review and diff workflows are unavailableInstall git before using review flowsfj auth add-key failsfj needs both a username and a resolvable target hostRun fj auth add-key <username> in a configured repo or fj --host <host> auth add-key <username>``fj is not authenticated for the target hostREST may work, but CLI commands will failRun fj auth list to inspect configured hosts, then add the key for the target hostrepo not foundWrong owner or repo, wrong instance, or missing accessVerify owner/repo, the target instance, and token permissionscannot infer repositoryNo local git remote and no explicit repo selectionAsk the user for owner/repo, and include --host or a host-qualified target when neededHTTP 401 or HTTP 403Invalid token or insufficient scopeVerify token validity, scopes, and repo permissionsHTTP 404 from the APIWrong path or endpoint unsupported on this Forgejo versionRecheck the URL and confirm support in $FORGEJO_URL/api/swagger``fj lacks the requested operationCLI gap compared to Forgejo APIFall back to curl and jq using the REST API