omp-forgejo

A multi-server Forgejo integration for omp: repository context resolution, attention watches, issue and pull-request workflows, evidence-backed reviews, notifications, search, and Forgejo Actions operations.

omp-forgejo is designed for teams that use Forgejo instead of GitHub, especially when the same developer works across multiple Forgejo instances.

Why this package

A bare owner/repo#123 is not enough when two servers can contain the same owner, repository, or issue number. This package keeps server identity attached to every resource and resolves the active repository from local Git remotes when that resolution is unambiguous.

It also gives omp a single, safety-oriented interface for:

• Multiple Forgejo servers with separate credentials
• Issues, pull requests, comments, planning metadata, and subscriptions
• Pull-request diffs, checks, reviews, readiness, and guarded merges
• Forgejo Actions runs, jobs, bounded logs, dispatches, cancellation, reruns, and artifacts
• Session-scoped incremental timeline updates that avoid rereading an entire discussion
• Session-scoped one-shot issue and pull-request watches that wake omp on matching timeline metadata
• CI watches that wake omp when a pull request's Actions runs finish, and cross-server attention watches for new review requests and notifications
• Cross-server search that never drops the source server identity

Installation

Install the latest npm release:

omp plugin install omp-forgejo

Restart omp or run /reload, then create a configuration:

/fj-setup

/fj-setup opens a native, guided TUI. It asks where to save the configuration, walks through every server and credential provider, configures the tool activation mode, then shows a final summary before writing. No JSON editing is required.

Alternative package sources:

# Install directly from GitHub
omp plugin install github:alpertarhan/omp-forgejo

# Pin an exact npm version
omp plugin install omp-forgejo@0.11.1

Updates are install-driven: re-run omp plugin install with the new version.

Requirements and compatibility

• A current omp installation (18.1 or newer, so attention=context watch messages record context without steering the active run)
• One or more reachable Forgejo instances
• Either an authenticated fgj profile or one token environment variable per server
• Forgejo API permissions appropriate for the operations you want to use

The package is tested against Forgejo 16.0.2. Actions support is discovered per route from the instance's same-origin Swagger document; unsupported operations fail closed instead of assuming that every Forgejo release exposes the same endpoints.

Flexible omp versions

The omp host resolves the extension's peer dependencies (@oh-my-pi/pi-ai, @oh-my-pi/pi-coding-agent, @oh-my-pi/pi-tui) onto its bundled copies when it loads the extension, so normal omp updates do not require a matching omp-forgejo release. Development dependencies are locked with Bun only to keep this repository's CI reproducible.

Quick start

1. Install the package with omp plugin install omp-forgejo.
2. Restart omp or run /reload.
3. Run /fj-setup and choose global or project scope.
4. Add each server from an authenticated fgj profile or by naming an API-token environment variable.
5. Choose the tool activation mode, review the summary, and save.
6. Open a repository whose Git remote points at a configured server.
7. Run /fj-context and /fj-health.

Example prompts:

Show my review requests and failed Actions runs across every Forgejo server.

Read work:platform/api#123, summarize new timeline updates, and tell me what remains.

Review community:tools/runner!45. Build the review draft, but do not submit it.

List the latest failed Actions runs for work:platform/api and inspect the failed job log.

Guided setup

Run /fj-setup without arguments for the full four-step flow:

1. Scope — choose global configuration for every project or project-local configuration for the current workspace. /fj-setup global and /fj-setup project skip this question.
2. Servers — discover signed-in fgj instances or add API-token servers without a CLI. Add, reconfigure, or remove multiple servers; choose short aliases and optional SSH host aliases used by Git remotes.
3. Tools — choose whether activated Forgejo domains accumulate (full) or swap (lite).
4. Review — inspect the destination, server URLs, credential sources, token-variable availability, and remote aliases before saving.

The wizard can update an existing configuration or explicitly replace it. Esc cancels without writing. API token values are never requested or stored; the wizard writes only environment variable names. Configuration is validated, written atomically with owner-only permissions, and rejected if another process changes the file while the wizard is open.

The JSON examples below remain useful as an advanced reference, but normal installation and reconfiguration do not require editing them.

Configuration

Configuration is loaded from two locations:

• Global: ~/.omp/agent/forgejo.json (or ~/.omp/profiles/<name>/agent/forgejo.json under omp --profile <name>)
• Project: <project>/.omp/forgejo.json

Set OMP_FORGEJO_CONFIG=/absolute/path/to/forgejo.json to override the global path. Trusted project configuration can add or replace server aliases and override tool settings. Project-local configuration and Git/SSH repository discovery are ignored until omp marks the project trusted; global configuration remains available.

Set tools.mode to lite to bound the model context the toolkit's tools occupy. In lite mode the forgejo_tools loader swaps domains instead of accumulating them: activating a domain deactivates the other Forgejo domain tools, so the session carries at most the schemas of the latest activation. The default full mode keeps activated domains for the rest of the session.

Inline plaintext token fields are rejected. Use the CLI-independent env provider with tokenEnv, or use the optional fgj provider.

Optional: fgj credential store

{
  "servers": {
    "work": {
      "hostname": "git.work.example",
      "credentialProvider": "fgj",
      "remoteHosts": ["forgejo-work"]
    },
    "community": {
      "hostname": "code.community.example",
      "credentialProvider": "fgj",
      "remoteHosts": ["forgejo-community"]
    }
  },
  "tools": {
    "mode": "full"
  }
}

Use fgjConfig when the CLI configuration is not at its default path:

{
  "hostname": "git.work.example",
  "credentialProvider": "fgj",
  "fgjConfig": "/absolute/path/to/fgj/config.yaml"
}

Tokens are resolved once and cached for the session. If the server rejects a cached fgj token with 401, the toolkit drops it, resolves a fresh token, and retries the request exactly once before surfacing the error.

API token credentials (no CLI required)

{
  "servers": {
    "work": {
      "baseUrl": "https://git.work.example",
      "hostname": "git.work.example",
      "credentialProvider": "env",
      "tokenEnv": "FORGEJO_WORK_TOKEN",
      "remoteHosts": ["forgejo-work"]
    }
  }
}

export FORGEJO_WORK_TOKEN='...'
omp

Use a separate, least-privilege Forgejo API token for every server. The environment provider reads only the named variable and never invokes fgj or another CLI. Required scopes depend on the enabled operations: repository and issue reads for normal inspection; write scopes for comments and metadata; notification scopes for inbox updates; and repository permissions for Actions or merge operations.

Server fields

Field	Required	Description
baseUrl	One of baseUrl or hostname	Absolute HTTP(S) Forgejo URL. Subpath installations are supported.
hostname	One of baseUrl or hostname	Hostname, optionally with a port, used by fgj and remote matching.
credentialProvider	No	env or fgj; defaults to env.
tokenEnv	For env	Environment variable containing the Forgejo API token.
fgjConfig	No	Optional absolute or relative path passed to fgj --config.
remoteHosts	No	Extra Git/SSH hostnames or SSH aliases that identify this server.

See examples/forgejo.json for a complete configuration.

Resource identity and repository resolution

Human-readable references:

work:platform/api              repository
work:platform/api#123          issue
work:platform/api!45           pull request

Canonical references are also accepted:

fj://work/platform/api
fj://work/platform/api/issues/123
fj://work/platform/api/pulls/45

For tool calls, an explicit qualified ref wins. The bare repository form is accepted wherever a repository target is enough (listing, creating, searching, /fj-open); actions that target one issue or pull request require the #N/!N index form. Otherwise server, owner, and repo must be supplied together. If neither is supplied, the package uses the repository selected from local Git remotes or /fj-server.

The remote resolver understands HTTPS, ssh://, SCP-style SSH URLs, ports, .git suffixes, Forgejo subpaths, and SSH host aliases. If multiple configured repositories match, it stops and requires an explicit choice.

Slash commands

Command	Purpose
/fj-setup [global|project]	Guided TUI for scope, fgj or API-token servers, Git aliases, tool activation, review, and safe writing.
/fj-context	Show the active server and repository.
/fj-server [alias]	Select a server for the current session.
/fj-health	Authenticate and report every configured server's Forgejo version.
/fj-open [qualified-ref]	Open the active repository or exact issue/PR in the browser.

omp tools

The package registers nine model-callable tools. Users normally describe the desired operation instead of constructing JSON manually.

By default, only forgejo_context and the compact forgejo_tools loader are active, and only in repositories whose Git remotes resolve to a configured Forgejo server; everywhere else the toolkit's tools stay out of the model context entirely. The loader activates at most four requested issue, pull, review, Actions, notification, search, or watch domains per call, additively for the current session, and replies with a per-domain action cheatsheet so the next call uses the right action on the first try; a new session returns to the compact set. There is deliberately no "load everything" option. The bundled skills request only their required domains and are discovered by omp's plugin skill provider whenever the package is enabled. This keeps seven larger schemas out of omp's initial context and avoids rebuilding the system prompt when a domain is activated, without delaying slash commands.

With tools.mode set to lite (see Configuration), activation is a swap: each forgejo_tools call deactivates the Forgejo domain tools it did not select, so the session context never carries more than the latest activation's schemas.

If you use only the raw tools and slash commands, disable the two workflow skills in ~/.omp/agent/config.yml:

disabledExtensions:
  - skill:forgejo-issue-to-pr
  - skill:forgejo-pr-review

The extension and all tools remain available; only automatic forgejo-issue-to-pr and forgejo-pr-review skill selection is disabled.

Tool	Actions
forgejo_context	current, servers, select, whoami, health, capabilities, resolve_ref
forgejo_tools	Activate one to four Forgejo tool domains for the current session
forgejo_search	issues, pulls, repositories, users
forgejo_notifications	list, get, mark_read, mark_unread, mark_all_read
forgejo_issue	list, get, timeline, updates, create, update, comment, get_comment, edit_comment, delete_comment, subscription, subscribe, unsubscribe, set_labels, set_assignees, set_milestone, clear_milestone, set_due_date, clear_due_date, close, reopen; refs[] batches get/update/close/reopen
forgejo_pull	list, get, timeline, updates, comment, get_comment, edit_comment, delete_comment, subscription, subscribe, unsubscribe, files, diff, commits, checks, create, update, set_labels, set_assignees, set_milestone, clear_milestone, set_due_date, clear_due_date, set_maintainer_edit, close, reopen, mark_draft, mark_ready, request_reviewers, remove_reviewers, readiness, merge; refs[] batches, prs[] batch create
forgejo_review	list, get, get_comments, create_draft, add_inline_comment, preview, submit, discard
forgejo_actions	list, get, jobs, job_log, dispatch, cancel, rerun, artifacts, artifact, download_artifact
forgejo_watch	start, list, stop for one-shot timeline, CI, and attention watches

forgejo_watch starts only after its watch domain is loaded. Watches are in-memory and scoped to the current omp session: unloading the lazy tool does not stop active watches, while session shutdown, replacement, reload, or a new session closes them. A match, timeout, or permanent failure completes a watch once. attention=turn steers or starts an agent turn; attention=context adds context without starting one. include_self=false filters timeline events by actor and merge transitions by merged_by; Forgejo's issue/PR state response does not identify who closed or reopened a resource, so those two transition filters cannot distinguish self-authored changes. The closed filter matches non-merge closes only; use merged (or feedback for review activity) to observe merges. An idle watch gets one final poll when its timeout expires, so a match that lands on the deadline is reported instead of a timeout.

Besides per-ref timeline watches, forgejo_watch starts two source watches. events=["ci"] on a pull-request ref polls the pull's current head SHA and wakes once any Actions run that was in flight or started after arming finishes (ci-success, ci-failure, ci-cancelled, ci-skipped), following new pushes to a fresh head SHA; runs that were already terminal when the watch armed are treated as baseline and never re-reported. target=review_requests or target=notifications watches the authenticated user's incoming review requests or unread notifications across every configured server (or a servers subset via the tool), seeding a silent baseline and waking on new items — the kind of wake a notification center gives a human, delivered to the agent instead. Degraded servers do not hold the watch hostage: healthy servers still wake the agent, a server unreachable at arming is re-baselined silently on recovery, and action=list reports degradedServers. An incomplete timeline scan still matches events from its fetched pages, grows its scan capacity, and fails loudly rather than live-locking once capacity is maximal.

Wake messages contain only bounded toolkit-generated metadata: an exact follow-up hint (forgejo_pull action=updates, forgejo_actions action=jobs, or forgejo_pull action=get), a re-arm hint for continuing a completed watch, item URLs where the toolkit generates them, and for attention items a sanitized 120-character title — remote bodies, diffs, run titles, and raw errors are always excluded. Timeline cursor state stores fixed-size event fingerprints rather than remote bodies or titles.

Model-visible metadata and discussion output defaults to 16 KB. Pull-request diffs, Actions job logs, and watch lists default to 32 KB. max_bytes can raise or lower configurable budgets but is hard-capped at 128 KB; truncation is explicit, and paginated results retain recovery metadata. Cross-server search includes a bounded, single-line body preview; use the qualified result with forgejo_issue or forgejo_pull when the complete body is needed. Oversized hidden tool details are compacted before omp persists them, retaining small identifiers and recovery fields rather than duplicating full remote payloads in session history. Artifact downloads use the separate max_download_bytes limit and write ZIP bytes to a deliberate workspace path instead of returning the archive to the model.

Incremental conversations

Issue and pull-request updates calls keep a lightweight cursor in the current omp session:

• The first call initializes a baseline without downloading historical timeline pages unless since is provided.
• Later calls fetch only the relevant time window and deduplicate events by stable event versions.
• Issue state/title changes and pull-request head SHA changes are reported with timeline events.
• A truncated or incomplete pagination scan does not advance the cursor.
• Cursors are intentionally in-memory and disappear when the omp session ends.

This reduces model context without persisting potentially sensitive issue bodies to disk.

Pull-request reviews and merges

Review drafts stay in memory until discarded or submitted. Replacing an existing draft requires replace: true. Inline comments are previewed with file and line positions. Submission always shows the complete draft and requires interactive confirmation.

Merge operations:

1. Fetch current pull-request metadata, checks, and reviews.
2. Reject failed checks, missing approvals, conflicts, or a changed head.
3. Show the server, repository, strategy, and expected head SHA.
4. Ask for interactive confirmation.
5. Re-fetch readiness and submit the guarded merge request.

Mutation approvals

Every confirmation dialog offers: Allow once, Always allow on all servers and repositories this session, Always allow on all servers and repositories (save globally), and Cancel. Saved approvals use stable action keys such as pull.merge in allowedMutations in the global config only — a committed project config can never pre-approve mutations. Active omp sessions re-read saved approvals before each mutation, and cross-process locking prevents concurrent sessions from overwriting each other's choices. Approved mutations (saved or session) also run without a UI, so they work in print mode; without an approval, headless sessions still fail closed.

The toolkit does not push local branches through the Forgejo API. Local Git remains the source of truth for branch creation, commits, rebases, and pushes.

Forgejo Actions

Read operations support runs, jobs, bounded job logs, and artifacts. Mutations support workflow dispatch, cancellation, and reruns when the instance advertises the corresponding API route.

Safety properties:

• Dispatch, cancel, and rerun require a capability check and interactive confirmation.
• Dispatch input values are visible only in the local confirmation dialog; model-facing results contain input names, not values.
• Finished runs are not cancelled and running runs are not rerun.
• Job logs are byte-bounded and report truncation.
• Artifact downloads default to a 100 MB maximum and can never exceed the caller's configured bound.
• Artifact destinations must remain inside the current workspace.
• Downloads use atomic writes and never overwrite an existing file without overwrite: true plus confirmation.

Included skills

forgejo-issue-to-pr

An issue-to-draft-PR workflow that reads the full conversation, preserves acceptance criteria, uses local Git for code changes, verifies the work, pushes to the resolved Forgejo remote, checks Actions, and opens a linked draft pull request.

forgejo-pr-review

An evidence-first review workflow that combines Forgejo metadata, timeline updates, diffs, checks, existing reviews, and local code. It builds one review draft, previews it, and submits only when the user explicitly requests publication.

omp's plugin skill provider discovers the bundled skills/ directory of an installed or linked package automatically. Skill entries are limited to name and description until read, so their context cost is two lines per skill; disable individual skills with disabledExtensions: ["skill:<name>"].

Security model

omp packages execute with the same operating-system permissions as omp. Review packages before installation.

omp-forgejo enforces these boundaries:

• No plaintext token configuration
• Separate credential providers and cached credentials per server
• Project-local configuration and repository discovery are disabled for untrusted projects
• Authorization headers are never forwarded outside the configured Forgejo API root
• Redirect-free Swagger capability discovery without credentials
• Token redaction in HTTP errors
• No automatic retry of mutations
• Exact server/repository identity for every mutation
• Comment ownership checks before edit/delete
• Interactive confirmation for destructive comment deletion, review publication, merges, workflow mutations, and artifact overwrites; "always allow" approvals persist to global config only, never project config
• Bounded UTF-8 model output, logs, diffs, timelines, and downloads
• Watch wake messages restricted to bounded event identifiers, types, actors, review IDs, timestamps, safe status codes, and normalized agent-authored notes; no remote body, title, diff, or raw error text

See SECURITY.md for private reporting and deployment guidance.

Development

This repository uses Bun for dependency management and scripts.

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run check

bun run check is the required local and CI gate. The npm package ships TypeScript source because omp loads extension modules directly; there is no generated build directory.

Project layout:

extensions/forgejo/       omp extension entry point
skills/                   Issue-to-PR and PR-review workflows
src/client.ts             Authenticated Forgejo HTTP client
src/remote-resolver.ts    Multi-remote repository resolution
src/attention.ts          Attention queries for review-request and notification watches
src/tools/                Model-callable Forgejo tools
src/actions.ts            Forgejo Actions request helpers
docs/                     Banner art and compositor (`docs/banner.html` renders `docs/banner.png`)
test/                     Deterministic Vitest contracts
examples/forgejo.json     Multi-server configuration example

See CONTRIBUTING.md for conventions, tests, and the pull-request checklist.

Release and provenance

• Versions follow Semantic Versioning.
• Changes are recorded in CHANGELOG.md.
• GitHub Actions verifies every push and pull request with Bun.
• GitHub releases publish to npm through npm trusted publishing with provenance.
• The omp-package keyword and omp manifest make releases discoverable by omp plugin tooling.

License

MIT © 2026 Alper Tarhan