โณ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.1.1

Forgejo Workflow

nerasse@nerasseโญ 1 starsยท last commit 7mo agoยท 0 open issues

Forgejo via fj and REST API for repos, issues, PRs, wiki, CI, and reviews.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

โ€”/10

// RATINGS

โญGitHub Stars
โญ 1 on GitHubGitHub โ†—

New / niche

๐ŸŸขProSkills Score
โ€”
๐Ÿ“

Not yet listed on ClawHub or SkillsMP

// README

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:
brew install forgejo-cli
  1. Make sure the other required tools are available:
command -v curl jq git
  1. Create an application token in Forgejo:
https://<your-forgejo-host>/user/settings/applications
  1. Export the required environment:
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.

  1. Add the same token to fj for the target host:
fj --host <your-forgejo-host> auth add-key <username>
  1. Verify readiness:
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:

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:

VariableRequiredExamplePurpose
FORGEJO_URLYeshttps://<your-forgejo-host>Base URL of the Forgejo instance for this skill's REST and instance-selection workflow
FORGEJO_TOKENYesforgejo_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:

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:

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:

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

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

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

License

MIT-0

// HOW IT'S BUILT

// FILES

8 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md11 KBc922d4c304f3upstream โ†—
    ---
    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 |
    
  • README.md5.3 KBfc9aa39fbb43upstream โ†—
    # 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
    
  • references/api-cheatsheet.md5.2 KBb24f94da4d0bupstream โ†—
    # 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
    ```
    
  • references/ci-actions.md3.5 KBef14dd6fe700upstream โ†—
    # 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
    
  • references/code-review.md6.2 KBb0194551e892upstream โ†—
    # 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
    
  • AGENTS.md1.5 KB9002f213787bupstream โ†—
    # 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.
    
  • CHANGELOG.md848 B8ee0c4d2cb9fupstream โ†—
    # 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.
    
  • LICENSE902 B622aba41ce39upstream โ†—
    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.
    

Plain-text copy, no login: /skill-bundles/nerasse-forgejo-skill.md

// REPO STATS

1 stars
0 open issues
Last commit: 7mo ago