Crate vgi_forge_forgejo 

Forgejo adapter for VGI git namespaces.

Implements vgi_forge::Forge for a Forgejo instance (and Gitea, best effort), acting as one community’s bot user on it (§5.9 of the design). Forgejo has no GitHub-App equivalent, so the differences are about identity, merges and self-hosting:

• Identity. A dedicated bot user with an access token scoped to BOT_TOKEN_SCOPES. It is long-lived, so it is held as a Secret (zeroized, never printed), swappable in place, and rotated by the bridge in two phases (ForgejoForge::mint_token, then ForgejoForge::retire_token once the new one is persisted) — which needs the bot’s password, because Forgejo mints tokens only under basic auth. Whether the bridge holds that password is an explicit choice (TokenRotation).
• Capabilities by probing. ForgejoForge::connect reads /api/v1/version and switches off what the instance lacks (fast-forward-only merges, the Actions variables API) before a plan is built, rather than failing half-way through one.
• Binding. The admin signs in through the bridge’s OAuth2 app (authorisation code + PKCE). The bridge confirms they own the org, uses that one-time token to put the bot in a vgi-bridge team (admin, “create repositories”) and to create the org webhook, then wipes it.
• Roles. Owner → admin collaborator; maintainer → write and the default branch’s merge allow-list; committer → nothing (or write by opt-in). Logins are looked up fresh by numeric id before each change.
• Bootstrap. Fast-forward-only merges, the workflow at .forgejo/workflows/verify-trust.yml (action by full URL, pinned by SHA, version and sha256 pinned), the variables, and a branch protection that lets nobody push, applies to admins, requires the check’s status context, restricts merging to the allow-list, and protects the workflow paths so no PR can rewrite its own check.
• Webhooks. X-Forgejo-Signature (or X-Gitea-Signature), hex HMAC-SHA256 of the raw body, checked in constant time before parsing.

The HTTP layer is a thin reqwest client, like the GitHub adapter’s: redirects off, a configurable base URL, and the credential named on every request.

Re-exports

pub use version::Features;

pub use version::Flavor;

pub use version::InstanceInfo;

Modules

plan

Forgejo’s bootstrap plan (§5.9) and the files it commits.

version

What an instance is, from GET /api/v1/version, and what it can do.

webhook

Webhook verification and translation (§5.6).

Structs

Credentials

Everything secret the adapter holds. Every field zeroizes on drop and prints as <redacted>.

ForgejoConfig

How to reach one Forgejo (or Gitea) instance as one bot user.

ForgejoForge

The Forgejo adapter: one bot user on one Forgejo (or Gitea) instance.

MintedToken

What ForgejoForge::mint_token minted, now in use.

RefreshReport

What ForgejoForge::refresh_managed_files did, for the audit log.

Secret

A secret string — a token, a key, a webhook secret.

TokenRef

One of the bot’s access tokens, by the id and name Forgejo lists it under. Holds no secret.

Enums

MergeFallback

What to do when the instance cannot restrict merges to fast-forward only (Forgejo before 7, Gitea before 1.22).

TokenRotation

How the bot token is rotated — an explicit choice, because Forgejo only mints and deletes access tokens under basic authentication (the /users/{name}/tokens endpoints refuse token auth), so rotation without a human means the bridge holds the bot’s password too.

Constants

BOT_TOKEN_SCOPES

Scopes the bot’s access token needs, and no more:

DEFAULT_ACTIONS_BASE

Where a bare owner/repo[/path]@sha action reference is resolved: the verify-trust action lives on GitHub.

DEFAULT_CHECKOUT_ACTION

actions/checkout v4.4.0, by full URL and commit. Full URL because a Forgejo runner resolves a bare owner/repo against the instance’s own default actions host; v4 because it runs on node20, which every forgejo-runner supports (v5+ needs node24).

DEFAULT_RUNS_ON

The runner label the verify-trust job asks for.

DEFAULT_TEAM

The organisation team the bot is put in at bind.

TOKEN_NAME_PREFIX

Name prefix of the tokens ForgejoForge::mint_token mints. Only for recognising them in the bot’s token list; nothing is deleted by prefix.