# Forgejo Workflow

Adopt this skill: https://proskills.md/skills/other/nerasse-forgejo-skill

Page: https://proskills.md/skills/other/nerasse-forgejo-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 11091
sha: c922d4c304f3a84460b15574adfd99ebd5707751
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/SKILL.md

```text
---
name: Forgejo Workflow
description: Forgejo via fj and REST API for repos, issues, PRs, wiki, CI, and reviews.
version: 0.1.1
homepage: https://github.com/nerasse/forgejo-skill
metadata:
  openclaw:
    emoji: "🦊"
    homepage: https://github.com/nerasse/forgejo-skill
    requires:
      bins:
        - fj
        - curl
        - jq
        - git
      env:
        - FORGEJO_URL
        - FORGEJO_TOKEN
    primaryEnv: FORGEJO_TOKEN
    install:
      - id: brew
        kind: brew
        formula: forgejo-cli
        bins:
          - fj
        label: Install Forgejo CLI (brew)
---

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://<your-forgejo-host>`, not an `/api/v1` endpoint.

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

## Required environment

| Variable | Required | Example | Purpose |
|---|---|---|---|
| `FORGEJO_URL` | Yes | `https://<your-forgejo-host>` | Base URL of the target Forgejo instance for this skill's REST and instance-selection workflow |
| `FORGEJO_TOKEN` | Yes | `forgejo_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:

    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:

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

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

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

    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/<base>` 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 <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

| Symptom | Likely cause | Action |
|---|---|---|
| `FORGEJO_URL` is not set | Required instance URL missing | Export `FORGEJO_URL` before running `fj` or REST workflows |
| `FORGEJO_TOKEN` is not set | Required application token missing | Create a token in Forgejo and export `FORGEJO_TOKEN` |
| `fj: command not found` | `forgejo-cli` is not installed | Install `fj` with the supported metadata installer or another package source |
| `curl: command not found` or `jq: command not found` | REST fallback tools are missing | Install the missing system tools before using REST workflows |
| `git: command not found` | Local review and diff workflows are unavailable | Install `git` before using review flows |
| `fj auth add-key` fails | `fj` needs both a username and a resolvable target host | Run `fj auth add-key <username>` in a configured repo or `fj --host <host> auth add-key <username>` |
| `fj` is not authenticated for the target host | REST may work, but CLI commands will fail | Run `fj auth list` to inspect configured hosts, then add the key for the target host |
| `repo not found` | Wrong owner or repo, wrong instance, or missing access | Verify `owner/repo`, the target instance, and token permissions |
| `cannot infer repository` | No local git remote and no explicit repo selection | Ask the user for `owner/repo`, and include `--host` or a host-qualified target when needed |
| `HTTP 401` or `HTTP 403` | Invalid token or insufficient scope | Verify token validity, scopes, and repo permissions |
| `HTTP 404` from the API | Wrong path or endpoint unsupported on this Forgejo version | Recheck the URL and confirm support in `$FORGEJO_URL/api/swagger` |
| `fj` lacks the requested operation | CLI gap compared to Forgejo API | Fall back to `curl` and `jq` using the REST API |
```

## File: README.md
size: 5458
sha: fc9aa39fbb4323accb70fe26b1469b66dcf7b301
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/README.md

````text
# Forgejo Workflow

OpenClaw skill for working with self-hosted Forgejo instances through `fj`, the
Forgejo REST API, and local `git` for review workflows. Published on ClawHub as
`forgejo-fj-api`.

## What this skill does

- Repositories, issues, pull requests, and releases
- Wiki reads through `fj` and wiki writes through the REST API
- Organization labels through `fj`; repository labels through the REST API by default, with `fj repo labels` available on current source builds but not packaged `0.4.x` releases; milestones through the REST API
- Forgejo Actions and CI status inspection
- Structured pull request review workflow

## Setup

Use one of these setup paths depending on whether you already have Forgejo
credentials.

### Manual setup

1. Install `fj`:

```bash
brew install forgejo-cli
```

2. Make sure the other required tools are available:

```bash
command -v curl jq git
```

3. Create an application token in Forgejo:

```text
https://<your-forgejo-host>/user/settings/applications
```

4. Export the required environment:

```bash
export FORGEJO_URL=https://<your-forgejo-host>
export FORGEJO_TOKEN=<your-token>
```

`FORGEJO_URL` must point to the target Forgejo instance, not to this skill
repository URL.

5. Add the same token to `fj` for the target host:

```bash
fj --host <your-forgejo-host> auth add-key <username>
```

6. Verify readiness:

```bash
command -v fj curl jq git
test -n "$FORGEJO_URL" && test -n "$FORGEJO_TOKEN"
fj auth list
```

### Prompt-guided setup

The assistant can guide setup, verify what is missing, and give exact commands.
It cannot create the Forgejo token for you; token creation still happens in the
Forgejo web UI.

If you already have credentials:

```text
Set up this Forgejo skill for https://<your-forgejo-host>. I already have a token and my Forgejo username is alice. First check whether fj, curl, jq, and git are available. If one of them is missing and OpenClaw can install it, install it. Then assume FORGEJO_URL and FORGEJO_TOKEN may already be available either from the OpenClaw .env loaded for this session or from exported shell variables, verify whether they are present, tell me the exact fj --host <your-forgejo-host> auth add-key alice command to run if fj auth is not ready yet, and finally tell me clearly whether the skill is fully ready, partially ready, or blocked, and what is still missing if anything.
```

## Configuration model

This skill targets one active Forgejo instance at a time.

Required environment:

| Variable | Required | Example | Purpose |
|---|---|---|---|
| `FORGEJO_URL` | Yes | `https://<your-forgejo-host>` | Base URL of the Forgejo instance for this skill's REST and instance-selection workflow |
| `FORGEJO_TOKEN` | Yes | `forgejo_pat_...` | Application token for this skill's REST examples and recommended `fj` setup |

Repository targeting:
- Resolve the repository from the current git remote when possible
- Outside a local clone, pass an explicit repo target and ensure `fj` can also resolve the host via `--host`, a host-qualified repo, or other existing CLI context
- Do not assume a public default Forgejo host

## Quick start

`fj` itself stores auth in its own keyring/config flow. These env vars are part
of this skill's explicit configuration contract, especially for REST fallback.

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

Run a repository command:

```bash
fj --host <your-forgejo-host> repo view owner/repo
```

Inside a local clone, `fj issue search` and `fj pr search` can use repository
context from the current remote.

Outside a local clone, many issue and pull-request commands use embedded targets
such as `owner/repo#42` rather than `--repo owner/repo`.

Use the REST API for coverage gaps:

```bash
curl -sS \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Accept: application/json" \
  "$FORGEJO_URL/api/v1/repos/owner/repo" | jq .
```

## Readiness check

Use this quick check to see whether the skill is ready to operate cleanly:

```bash
command -v fj curl jq git
test -n "$FORGEJO_URL" && test -n "$FORGEJO_TOKEN"
fj auth list
```

Interpretation:
- if a binary check fails, install the missing tool first
- if an env check fails, export the missing value first
- if `fj auth list` does not include the target host, add the key for that host first

If `fj` is missing but `curl` and `jq` are available, the REST references can
still cover API-only tasks.

## Install the skill

```bash
clawhub install forgejo-fj-api
```

## Included references

- `references/api-cheatsheet.md` for verified REST endpoints and payload shapes
- `references/code-review.md` for the Forgejo PR review workflow and output format
- `references/ci-actions.md` for Actions and CI inspection guidance

## Compatibility

- Targeted at self-hosted Forgejo instances
- Requires `fj` for the CLI path, `curl` and `jq` for the REST path, and `git` for review flows
- Requires a valid Forgejo application token
- `fj repo labels` is available on current source builds, but not packaged `0.4.x` releases
- Actions and some API details can vary by Forgejo version; check `$FORGEJO_URL/api/swagger` when behavior differs
- OpenClaw eligibility gating checks declared bins and env vars at load time, but sandboxed runs also need the same tools available inside the sandbox

## Publish

```bash
clawhub publish . --slug forgejo-fj-api --version 0.1.1
```

## License

MIT-0
````

## File: references/api-cheatsheet.md
size: 5354
sha: b24f94da4d0b229251ff0150c1e0f729462bfed9
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/references/api-cheatsheet.md

````text
# Forgejo API Cheatsheet

This reference assumes `FORGEJO_URL` and `FORGEJO_TOKEN` are already set.

If required bins, env vars, or `fj` setup are missing, return to `SKILL.md`
prerequisites, readiness checks, or troubleshooting before proceeding.

Use these endpoints when `fj` does not support the requested operation.

The examples in this skill use these JSON request headers:

```bash
-H "Authorization: token $FORGEJO_TOKEN"
-H "Content-Type: application/json"
-H "Accept: application/json"
```

Forgejo also accepts bearer-style authorization headers. The examples in this
skill use the `Authorization: token ...` form for consistency.

## Wiki writes

Create a page:

```http
POST /repos/{owner}/{repo}/wiki/new
```

Request body:

```json
{
  "title": "Page Title",
  "content_base64": "<base64>",
  "message": "Create wiki page"
}
```

Update a page:

```http
PATCH /repos/{owner}/{repo}/wiki/page/{pageName}
```

Request body:

```json
{
  "title": "Page Title",
  "content_base64": "<base64>",
  "message": "Update wiki page"
}
```

If `title` is omitted or empty on update, the current page name is kept.

Delete a page:

```http
DELETE /repos/{owner}/{repo}/wiki/page/{pageName}
```

List or read pages:

```http
GET /repos/{owner}/{repo}/wiki/pages
GET /repos/{owner}/{repo}/wiki/page/{pageName}
GET /repos/{owner}/{repo}/wiki/revisions/{pageName}
```

Encode wiki content to base64 before sending it:

```bash
printf '%s' "# My Page
Page content here" | base64
```

The wiki create and edit request body uses the `CreateWikiPageOptions` schema in
Swagger. Confirm field names against the target instance's `/api/swagger` if you
need to script it precisely for a specific Forgejo version.

## Repository labels

List labels:

```http
GET /repos/{owner}/{repo}/labels
```

Create a label:

```http
POST /repos/{owner}/{repo}/labels
```

```json
{
  "name": "bug",
  "color": "#d73a4a",
  "description": "Bug report",
  "exclusive": false,
  "is_archived": false
}
```

Update a label:

```http
PATCH /repos/{owner}/{repo}/labels/{id}
```

Delete a label:

```http
DELETE /repos/{owner}/{repo}/labels/{id}
```

## Milestones

List milestones:

```http
GET /repos/{owner}/{repo}/milestones
GET /repos/{owner}/{repo}/milestones/{id}
```

Create a milestone:

```http
POST /repos/{owner}/{repo}/milestones
```

```json
{
  "title": "v2.0",
  "description": "Release milestone",
  "due_on": "2026-06-01T00:00:00Z",
  "state": "open"
}
```

Update a milestone:

```http
PATCH /repos/{owner}/{repo}/milestones/{id}
```

Delete a milestone:

```http
DELETE /repos/{owner}/{repo}/milestones/{id}
```

## Pull request reviews with inline comments

Create a review with summary and inline comments:

```http
POST /repos/{owner}/{repo}/pulls/{index}/reviews
```

```json
{
  "body": "Review summary",
  "event": "COMMENT",
  "comments": [
    {
      "path": "src/main.go",
      "new_position": 42,
      "body": "Potential nil pointer here"
    }
  ]
}
```

The Swagger schema also defines `old_position` for comments on removed lines and
an optional `commit_id` at the review level.

Supported review submission events are stable across checked Forgejo `v13.x`,
`v14.x`, and current source:
- `COMMENT`
- `APPROVED`
- `REQUEST_CHANGES`

Current server behavior is stricter than the enum list alone suggests:
- `COMMENT` requires a body or inline comments
- `REQUEST_CHANGES` requires a body
- `APPROVED` does not require a body
- omitted or unrecognized events fall back to a pending review flow
- `PENDING` can create a pending review but cannot be submitted as a final review
- `REQUEST_REVIEW` is not a supported create/submit review event; use the
  requested-reviewers endpoints instead

Only send `APPROVED` if the user explicitly asked for approval.

## Notifications

List all notifications:

```http
GET /notifications
GET /notifications/new
GET /notifications/threads/{id}
```

List repository notifications:

```http
GET /repos/{owner}/{repo}/notifications
```

Change notification status for the current user:

```http
PUT /notifications
PUT /repos/{owner}/{repo}/notifications
PATCH /notifications/threads/{id}
```

Current implementations also accept status controls such as `to-status` for read,
unread, or pinned transitions. Check the target instance Swagger before relying
on specific notification-status mutations.

Current server behavior also supports notification filters such as
`status-types`, `subject-type`, `all`, and `last_read_at` on the notification
endpoints.

## Pull request metadata

Use the pull request endpoint to discover the base branch, head branch, head SHA,
and merge state before reviewing or merging:

```http
GET /repos/{owner}/{repo}/pulls/{index}
```

Useful fields commonly include:
- `base.ref`
- `head.ref`
- `head.sha`
- `mergeable`
- `draft`
- `merged`

## Pagination pattern

For paginated endpoints, use `page` and `limit` parameters and keep paging until
the response or available pagination metadata shows there are no more results.

Example shell loop:

```bash
page=1
while true; do
  curl -sS -D headers.txt \
    -H "Authorization: token $FORGEJO_TOKEN" \
    -H "Accept: application/json" \
    "$FORGEJO_URL/api/v1/repos/$OWNER/$REPO/issues?page=$page&limit=50"
  page=$((page + 1))
  # Stop after the last page based on the response size or pagination metadata when available.
done
```
````

## File: references/ci-actions.md
size: 3594
sha: ef14dd6fe700a56c7049bb39b325d95b6d17c802
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/references/ci-actions.md

````text
# Forgejo CI and Actions

This reference assumes `FORGEJO_URL` and `FORGEJO_TOKEN` are already set.

If required bins, env vars, or `fj` setup are missing, return to `SKILL.md`
prerequisites, readiness checks, or troubleshooting before proceeding.

Use this reference when `fj` is not enough for CI or Forgejo Actions tasks.

## Fast path with `fj`

Use `fj` first for quick checks:

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

Use this when the user mainly needs recent runs or a simple status
summary.

## REST API coverage

Forgejo API coverage for Actions varies by Forgejo version. Check the target
instance at:

```text
https://<your-forgejo-host>/api/swagger
```

Current Forgejo source exposes these Actions endpoints:

```http
GET /repos/{owner}/{repo}/actions/tasks
GET /repos/{owner}/{repo}/actions/runs
GET /repos/{owner}/{repo}/actions/runs/{run_id}
GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs
POST /repos/{owner}/{repo}/actions/workflows/{workflowfilename}/dispatches
```

`GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs` is present in current
source, but was not found in any checked published tags. Treat it as unreleased
or branch-only unless the target instance Swagger documents it explicitly.

Job-log coverage is also version-sensitive. Checked Forgejo source exposes job-log
paths as web routes rather than stable REST API endpoints, and the URL shape has
changed across versions.

Workflow dispatch requires a `ref`. Current server implementations also support
optional `inputs`, and `return_run_info=true` can switch the response from `204`
to a created-run payload.

## Checking CI for a pull request

1. Get the pull request metadata and head SHA.

```bash
curl -sS \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Accept: application/json" \
  "$FORGEJO_URL/api/v1/repos/$OWNER/$REPO/pulls/55" | jq -r '.head.sha'
```

2. Fetch commit statuses.

```bash
curl -sS \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Accept: application/json" \
  "$FORGEJO_URL/api/v1/repos/$OWNER/$REPO/statuses/$SHA" | jq '.[] | {context, status, target_url}'
```

Related status endpoints also exist under:

```http
GET /repos/{owner}/{repo}/commits/{ref}/statuses
GET /repos/{owner}/{repo}/commits/{ref}/status
```

3. If needed, inspect workflow runs through the Actions endpoints.
4. Only use the run-jobs endpoint when the target instance Swagger documents it.

## Reading job logs

If the target instance exposes job and log endpoints in Swagger, use them.
Otherwise say the instance does not document those endpoints and fall back to the
best available run or status summary rather than inventing details.

## `fj-ex` as a last resort

`fj-ex` is a community extension that fills some gaps such as detailed logs,
artifacts, cancel, rerun, and workflow dispatch by scraping the web UI.

Use it only as an optional fallback, not as a required dependency.

Important constraints:
- It is not part of the core required toolchain
- It may break when the Forgejo web UI changes
- Prefer official API endpoints whenever they exist

## Failure handling

- If `fj actions tasks` works but detailed logs are missing, explain the CLI limitation
- In current `forgejo-cli` source, the listing command is `fj actions tasks`
- If an Actions API endpoint returns `404`, the Forgejo version may not expose it, or the endpoint may only exist on newer unreleased source
- If a status endpoint returns no checks, confirm the repository actually uses Forgejo Actions or commit statuses
- If run details are ambiguous, report uncertainty instead of guessing
````

## File: references/code-review.md
size: 6306
sha: b0194551e892a55d35b83b4e5043281194066717
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/references/code-review.md

````text
# Forgejo Pull Request Review Workflow

This reference assumes `FORGEJO_URL` and `FORGEJO_TOKEN` are already set.

This workflow also requires a local git clone and a working `git` binary. If the
required bins, env vars, or `fj` setup are missing, return to `SKILL.md`
prerequisites, readiness checks, or troubleshooting before proceeding.

Use this workflow when the user asks for a review of a Forgejo pull request.

## Review goal

Prioritize behavioral risk over style. Focus first on security, correctness,
breaking changes, test gaps, and performance regressions. Treat readability and
convention issues as secondary unless they hide a real defect.

## Workflow

1. Inspect the current worktree before checking out the pull request.

```bash
git status --porcelain
```

If the worktree is dirty, warn the user before switching branches.

`fj pr checkout` will fail on uncommitted changes, so do not treat this as a
soft warning only.

2. Check out the pull request.

```bash
fj pr checkout <number>
```

3. Determine the actual base branch of the pull request.

Prefer `fj pr view <number>` if it exposes the base branch clearly. Otherwise use
the API:

```bash
curl -sS \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Accept: application/json" \
  "$FORGEJO_URL/api/v1/repos/$OWNER/$REPO/pulls/<number>" | jq -r '.base.ref, .head.ref, .head.sha, .mergeable, .draft, .merged'
```

The examples in this skill use the `Authorization: token ...` form. Forgejo also
accepts bearer-style authorization headers.

4. Compute the merge base against the real base branch.

```bash
BASE_BRANCH=<base-branch>
BASE_COMMIT=$(git merge-base HEAD "$BASE_BRANCH")
```

5. Inspect the diff.

Overview:

```bash
git diff --stat "$BASE_COMMIT"..HEAD
```

Per file:

```bash
git diff "$BASE_COMMIT"..HEAD -- path/to/file
```

If the diff is large, review file by file.

6. Analyze the changes using the review criteria below.

7. Post the review.

Global comment:

```bash
fj pr comment <number> "<review body>"
```

Some PR commands can infer the PR number from the current branch, but keeping the
number explicit is safer for review workflows.

Inline comments, if needed:
- Use `POST /repos/{owner}/{repo}/pulls/{index}/reviews`
- See `references/api-cheatsheet.md`
- Use `new_position` for added lines and `old_position` for removed lines when needed
- `COMMENT` reviews need a body or inline comments; `REQUEST_CHANGES` needs a body

8. Keep the final action separate:
- Post comments by default
- Approve only if the user explicitly asks for approval
- Merge only if the user explicitly asks for merge

Note: `forgejo-cli` currently exposes pull-request comments and merge flows, but
not a full approval-review command surface in the documented PR subcommands. This
skill keeps approval posting in the API/reference path because approval and merge
must remain conceptually separate.

## Review priorities

Prioritize findings in this order:

| Priority | Area | What to look for |
|---|---|---|
| 1 | Security | Injection, auth bypass, secret exposure, SSRF, XSS, path traversal, unsafe permission changes |
| 2 | Correctness | Nil or null access, wrong conditions, race conditions, broken error paths, resource leaks |
| 3 | Breaking changes | API contract drift, schema changes, config or env changes, backward-incompatible behavior |
| 4 | Tests and observability | Missing coverage, missing edge cases, broken assertions, absent logging or metrics around risky paths |
| 5 | Performance and operations | N+1 queries, quadratic behavior, blocking I/O, large allocations, retry storms, bad timeouts |
| 6 | Maintainability | Oversized functions, unclear ownership, duplicated logic, naming or comment issues that hide risk |

## Severity model

Use these severity labels in the final review:

| Severity | Meaning | Typical action |
|---|---|---|
| Blocking | Likely bug, security risk, data loss, or breaking change | Do not approve; ask for changes |
| Important | Real weakness or missing safety net, but not clearly blocking | Call out explicitly; approval depends on user intent and risk tolerance |
| Minor | Quality improvement with low immediate risk | Keep concise and avoid drowning out higher-risk findings |

If you are not sure a finding is real, lower confidence in the wording instead of
presenting speculation as fact.

## Language-specific hot spots

If the diff includes these languages, pay extra attention to:

- Go: `if err != nil`, goroutine leaks, `defer` ordering, nil handling
- JavaScript or TypeScript: async error handling, unhandled promises, XSS in templates, unsafe casts
- Python: mutable default arguments, exception specificity, resource management, typing gaps
- Rust: `unwrap()` or `expect()` in unsafe contexts, ownership mistakes, `unsafe` blocks
- C# or VB.NET: null handling, `IDisposable`, `async void`, deferred LINQ behavior

## Output format

Use this review structure when posting a summary comment:

```markdown
## Code Review - PR #<number>

**Base:** `<base branch>` <- `<head branch>`
**Files changed:** <count>
**Lines:** +<added> / -<removed>

### Summary
- <1-2 bullets on overall risk and scope>

### Blocking findings
- `<file>:<line>` - <description, risk, and concrete fix direction>

### Important suggestions
- `<file>:<line>` - <description>

### Minor improvements
- `<file>:<line>` - <description>

### Positive notes
- ...

### Verdict
**Recommendation:** Request Changes | Comment | Approve
**Why:** <1-2 sentences>
```

Only recommend `Approve` when no blocking issues remain and the user explicitly
asked for approval.

## Large diff strategy

If the diff exceeds roughly 500 changed lines:

1. List changed files with `git diff --name-only "$BASE_COMMIT"..HEAD`
2. Review business logic files first
3. Review tests next
4. Review config and docs last
5. Consolidate findings into one final review comment
6. If time or context limits prevented full coverage, say which files were not deeply reviewed

## Common pitfalls

- Reviewing style instead of behavior
- Assuming the base branch is `main` without checking PR metadata
- Missing removed-line comments that require `old_position` instead of `new_position`
- Approving by default instead of keeping approval separate from comments
- Overstating certainty when the evidence is incomplete
````

## File: AGENTS.md
size: 1516
sha: 9002f213787be4a8523b66c604935cbdff4ef2c7
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/AGENTS.md

```text
# Project

`forgejo-skill` is an OpenClaw skill for self-hosted Forgejo via `fj`, REST API, and local `git` review workflows.
Main product files are Markdown: `SKILL.md`, `README.md`, `references/*.md`, `CHANGELOG.md`.
In this repo, `.md` files are usually shipped skill content, not ancillary docs.

# Changelog

- Inspect staged changes only.
- For changelog-only work, never run `git add`, commit, or push.
- Follow Keep a Changelog `1.1.0`: https://keepachangelog.com/en/1.1.0/
- Update only `## [Unreleased]` unless a specific version is requested.
- When releasing, create or update `## [<version>] - YYYY-MM-DD` from `Unreleased`.
- Keep entries concise, user-facing, actionable, and deduplicated.
- Treat core skill Markdown changes as product changes when they alter capability, setup, workflow, or references.
- Ignore only true ancillary changes such as `docs/`, guides, notes, images, and assets.

# Commit Message

- Propose a commit message only; do not commit.
- Use conventional commits: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `ci`, `build`.
- Keep it concise: `<type>: <summary>`.
- Match the staged changes and any changelog edits exactly.
- Prefer `feat` when the skill gains new user-facing capability or reference coverage.

# Release

- Start from staged changes as source of truth.
- Update affected product docs before changelog updates.
- For releases, stage required doc and changelog edits, create one normal commit, create an annotated tag, then push branch and tag.
```

## File: CHANGELOG.md
size: 848
sha: 8ee0c4d2cb9f1c615ff42a5238b046f80f7177fb
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/CHANGELOG.md

```text
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

## [0.1.1] - 2026-04-09

### Changed
- Changed the public skill name to `Forgejo Workflow` while keeping the published ClawHub slug `forgejo-fj-api`.

## [0.1.0] - 2026-04-09

### Added
- Added the initial Forgejo skill for self-hosted instances through `fj`, the REST API, and local `git` review workflows.
- Added setup and readiness guidance for required tools, environment variables, and `fj` authentication.
- Added REST API reference coverage for wiki writes, labels, milestones, notifications, pagination, and inline pull request reviews.
- Added CI and code review references for Actions inspection, pull request checkout, diff review, and review reporting.
```

## File: LICENSE
size: 902
sha: 622aba41ce398ec9f6978142e2cb7b7267150d42
upstream: https://github.com/nerasse/forgejo-skill/blob/HEAD/LICENSE

```text
MIT No Attribution

Copyright 2026 nerasse

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
