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:

$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://, not an /api/v1 endpoint.

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

Required environment

Authenticate fj with the same token when the target host is already inferable

from the current repository context:

fj auth add-key

If the current directory is not a Forgejo repository, or if you need to target a

different instance explicitly, pass the host:

fj --host auth add-key

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

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:

command -v fj curl jq git

Check required env vars:

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

Check fj auth for the target host:

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

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

There is no generic fj repo list command in forgejo-cli. To list repositories,

use user or organization commands such as:

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:

fj --repo owner/repo

For issue and pull-request commands that do not support --repo, use an embedded

target such as owner/repo#42.

Issues

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

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/ and may prompt to write git config.

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

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

fj release list

fj release create 0.1.0 --tag 0.1.0

Organizations and teams

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:

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

List wiki pages with fj:

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:

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 .
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=&limit=.

When fetching large result sets, keep paging until the response shape or

available pagination metadata indicates there are no more results.

Troubleshooting