forgejo-cli

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Forgejo CLI tools

## Authorization

Read freely. An explicit user request that names the Forgejo target and a
bounded write action authorizes that action. Otherwise, show the exact mutation
and ask for confirmation before running it.

Always confirm immediately before destructive, irreversible,
privilege-changing, or materially broader work. This includes merging or
closing pull requests, deleting content or tags, publishing or deleting
releases, cancelling runs, changing repository access, settings, variables, or
secrets, rewriting history, and any action whose effects exceed the request.

## Common commands

Prefer `fj --style minimal` for normal operations and `fgj` for structured output.
Replace `HOST/OWNER/REPO`, `PR`, `ISSUE`, and `QUERY` with your target values.
Commands without explicit targeting infer the repository from the checkout:

```sh
fj --style minimal pr view PR body
fj --style minimal pr view PR diff
fj --style minimal pr status PR
fj --style minimal pr status PR --wait
fj --style minimal issue view --remote origin ISSUE
fj --style minimal issue search --repo HOST/OWNER/REPO --state all 'QUERY'
```

Run independent reads in parallel. When the harness supports background commands
with completion notifications, run `status --wait` in the background and await
completion without polling. Distinguish pending policy gates from CI checks and
merge conflicts. A pending policy gate does not by itself indicate broken CI.

Search existing issues before creating one. With explicit authorization for the
target and issue creation, use an absolute body-file path, then read the created
issue back once:

```sh
fj --style minimal issue create --repo HOST/OWNER/REPO 'Issue title' --body-file /absolute/path/issue.md
```

Only after successful required checks, verification of mergeability, and
immediate confirmation of the merge, use the rebase form:

```sh
fj --style minimal pr merge PR --method rebase
```

## Tool choice and targeting

Both tools infer the repository from the checkout where possible. Use
`--repo HOST/OWNER/REPO` or `--remote NAME` with `fj`; with `fgj`, prefer
`--hostname HOST -R OWNER/REPO` to make the server explicit.

| Task                                          | Use                   | Command family                       |
| --------------------------------------------- | --------------------- | ------------------------------------ |
| Issues and basic PRs                          | `fj`                  | `fj issue`, `fj pr`                  |
| Wiki pages and wiki Git clone                 | `fj`                  | `fj wiki`                            |
| Tags                                          | `fj`                  | `fj tag`                             |
| Releases and release assets                   | `fj`                  | `fj release`                         |
| Actions run list and dispatch                 | Either                | `fj actions`, `fgj actions`          |
| Actions jobs, logs, watch, rerun, cancel        | `fgj`                 | `fgj actions run`                    |
| Machine-readable list/view output             | `fgj`                 | `--json`                             |
| Users, organizations, teams, repository units | `fj` for dedicated UX | `fj user`, `fj org`, `fj repo units` |
| AGit pull requests                            | `fj`                  | `fj pr create --agit`                |

Use command help when unsure about a flag. Before an API fallback, check
`fgj --help` once for an `api` subcommand. If the installed help lacks it, use a
supported dedicated command or another authenticated read-only path if needed.
Minimal text is not a stable machine-readable format; inspect the JSON shape
before selecting fields.

## Issues

Use `fj` for issue workflows:

```sh
fj issue search --repo HOST/OWNER/REPO "QUERY"
fj issue search --repo HOST/OWNER/REPO --state all
fj issue search --repo HOST/OWNER/REPO --labels bug --assignee USERNAME
fj issue view --remote origin ISSUE
fj issue view --remote origin ISSUE comments
fj issue create --remote origin "Issue title" --body "Issue description"
fj issue comment --remote origin ISSUE "Additional context"
fj issue assign --remote origin ISSUE USERNAME
fj issue edit --remote origin ISSUE title "Updated title"
fj issue edit --remote origin ISSUE body "Updated body"
fj issue edit --remote origin ISSUE labels --add documentation
fj issue close --remote origin ISSUE --with-msg "Closing because ..."
```

Omit `--body` or the positional body to edit content in the configured editor. Use `--body-file FILE` for longer text.

For JSON, use `fgj`. Issue views wrap the object in `issue`, rather than returning
bare issue fields. Verify the shape for your installed version:

```sh
fgj issue list --hostname HOST -R OWNER/REPO --json
fgj issue view ISSUE --hostname HOST -R OWNER/REPO --json | jq '.issue | {title, updated_at, body}'
```

## Pull requests

Use `fj` for normal Forgejo pull request workflows:

```sh
fj pr search --repo HOST/OWNER/REPO
fj pr search --repo HOST/OWNER/REPO --state all "QUERY"
fj pr view PR
fj pr view PR files
fj pr view PR commits
fj pr create --repo HOST/OWNER/REPO \
  --base main --head feature/example \
  "Describe the change" --body-file pr-body.md
fj pr comment PR "Review comment"
fj pr checkout PR --branch-name review-PR
fj pr close PR --with-msg "Closing because ..."
```

From nb-99/skillektion, MIT.

More from nb-99/skillektion