Forgejo

@dataverket/forgejov2026.10.05.4· 1d agoMODELS

01README

Forgejo (or Gitea) administration for swamp over the /api/v1 REST API with a scoped access token, in one model type, @dataverket/forgejo. A fork of @thomas/forgejo 2026.09.04.2 (MIT, copyright Thomas Elliott) merged with the methods dataverket had published as add-ons to it. The upstream base is kept: find-or-create organizations and repositories and converge their settings, collaborators and branch protection, pull mirrors from GitHub with a fleet-wide sync audit, pull requests opened, inspected with mergeability and CI state, and merged behind a guard, and webhooks audited or repointed without ever touching their secret. The base's own reachable check is dropped in favour of this package's two, and a check without the schema's defaults no longer aborts its request at once. The former add-ons, now part of the same type: Actions secrets (repo- or org-scoped, write-only), a runner registration token, runner listing and pruning, a verify-first repository rename, push mirrors (ensure, list, delete, sync now), a pull mirror that sends only the settings it is given, repository topics and units, pull-request assignment with every login checked first, issues filed by title with labels by name, labels of an organization or a repository, and verify-first deletes of a repository and of an organization: one already gone is a no-op, one with commits or with repositories is refused unless asked for explicitly, because Forgejo has no undelete. Two pre-flight checks: a policy check that apiUrl is the forge's base URL without a trailing /api/v1, and a live one that the token is still accepted. No secret value is recorded or logged: the registration token is marked sensitive, so swamp vaults it and records a reference; a mirror's source or remote credential is sent to Forgejo once and never stored; and a token the forge echoes back in an error is masked before it becomes data.

02Models1

@dataverket/forgejov2026.10.05.4forgejo.ts

Global Arguments

Argument	Type	Required	Description
apiUrl	string	yes	Forgejo base URL, e.g. https://git.example.com (no trailing /api/v1).
token	string	yes	Forgejo access token (Settings → Applications). Supply via vault:

fn health()

Server version (/api/v1/version) + health (/api/healthz). Read-only.

fn org_list()

List organizations (factory; a site-admin token sees all). Read-only.

fn repo_list(owner?: string)

List repositories — all the token can see, or one owner's (factory).

Argument	Type	Required	Description
owner?	string	no	Restrict to one org/user's repos. Omit to list every repo the token

fn user_list()

List user accounts via the admin API (factory; requires read:admin

fn mirror_status()

Audit every pull-mirror's sync health: last sync, interval, and a

fn webhook_audit(owner?: string, name?: string, expectedUrl?: string)

List every repository's webhooks and where they point (factory).

Argument	Type	Required	Description
owner?	string	no	Restrict to one org/user's repos. Omit to audit every repo the token
name?	string	no	Audit a single repository. Requires `owner`.
expectedUrl?	string	no	The URL every hook is supposed to point at. Supplying it populates

fn webhook_retarget(owner: string, name: string, url: string, matchUrl?: string)

Repoint an existing webhook at a new scheme/host/path. CONVERGE-ONLY:

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.
url	string	yes	The URL the matched hook(s) should POST to.
matchUrl?	string	no	Substring identifying WHICH hook to repoint (matched against the

fn org_ensure(name: string, description?: string, visibility?: enum, fullName?: string)

Find-or-create an organization and converge its description/

Argument	Type	Required	Description
name	string	yes	Org login name (find-or-create key).
description?	string	no	Org description to converge.
visibility?	enum	no	Org visibility to converge (Forgejo default: public).
fullName?	string	no	Display name to converge.

fn repo_ensure(owner: string, name: string)

Find-or-create a repository under an org or user and converge the

Argument	Type	Required	Description
owner	string	yes	Owning org or user login (an org must already exist — see org_ensure).
name	string	yes	Repository name (find-or-create key).

fn collaborator_ensure(owner: string, name: string, user: string, permission?: enum)

Grant a user access to a repository at a given permission level, or

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.
user	string	yes	Login of the user to grant access to.
permission?	enum	no	Access level to converge.

fn branch_protection_ensure(owner: string, name: string, rule: string)

Find-or-create a branch-protection rule for a branch or glob and

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.
rule	string	yes	Branch name or glob the rule applies to (find-or-create key), e.g.

fn branch_protection_list(owner: string, name: string)

List every branch-protection rule on a repository — the audit view

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.

fn mirror_ensure(owner: string, name: string, cloneAddr: string, service?: enum, authToken?: string, mirrorInterval?: string, description?: string)

Find-or-create a pull-mirror of an external repo (GitHub by default)

Argument	Type	Required	Description
owner	string	yes	Owning org or user login for the mirror.
name	string	yes	Mirror repository name (find-or-create key).
cloneAddr	string	yes	Source clone URL, e.g. https://github.com/<owner>/<repo>.git
service?	enum	no	Source service type (drives metadata migration).
authToken?	string	no	Source-side token for private sources (write-only; sent once to
mirrorInterval?	string	no	Periodic sync interval as a Go duration (e.g. "8h0m0s"; "0s" disables
description?	string	no	Mirror repo description.

fn mirror_sync_now(owner: string, name: string)

Queue an immediate pull-sync of a mirror (POST /mirror-sync).

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Mirror repository name.

fn pr_list(owner: string, name: string, state?: enum)

List a repository's pull requests with head/base, author and draft

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.
state?	enum	no	Which pull requests to list.

fn pr_get(owner: string, name: string)

Get one pull request including the server's mergeable verdict and

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.

fn pr_ensure(owner: string, name: string, head: string, base: string, title: string, body?: string)

Find-or-create a pull request for a head→base branch pair, and

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.
head	string	yes	Source branch. Use owner:branch for a cross-repo (fork) PR.
base	string	yes	Target branch, e.g. main.
title	string	yes	PR title (converged on an existing open PR).
body?	string	no	PR description (converged on an existing open PR).

fn pr_merge(owner: string, name: string, strategy?: enum, title?: string, message?: string)

Merge a pull request. NOT REVERSIBLE — this writes to the base

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.
strategy?	enum	no	Merge strategy (Forgejo's `Do`).
title?	string	no	Merge commit title override.
message?	string	no	Merge commit message override.

fn repo_archive(owner: string, name: string)

Archive a repository (read-only on the server). REVERSIBLE — undo

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.

fn repo_unarchive(owner: string, name: string)

Unarchive a repository. REVERSIBLE — undo with repo_archive.

Argument	Type	Required	Description
owner	string	yes	Owning org or user login.
name	string	yes	Repository name.

Resources

server(infinite)— Server version and health.

org(infinite)— An organization and its visibility/description.

repo(infinite)— A repository and its settings.

user(infinite)— A user account (admin view — never any credential).

collaborator(infinite)— A user's access level on a repository.

branch_protection(infinite)— A branch-protection rule and the constraints it enforces.

mirror(infinite)— A pull-mirror's sync health.

pull_request(infinite)— A pull request: state, mergeability, and head CI status.

webhook(infinite)— A repository webhook: where it posts, what triggers it, whether it

03Previous Versions8

2026.10.05.3Oct 5, 2026

Added 1 models. updated labels

2026.10.05.2Oct 5, 2026

2026.10.05.1Oct 5, 2026

updated labels

2026.10.04.2Oct 4, 2026

2026.10.04.1Oct 4, 2026

2026.09.30.1Sep 30, 2026

updated labels

2026.09.29.2Sep 29, 2026

2026.09.29.1Sep 29, 2026

04Stats

100 / 100

Downloads

Archive size

82.2 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/dataverket-org/swamp-extensions

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#forgejo #gitea #git #forge #actions #runners #mirroring #topics #issues #labels #mirrors #pull-requests #webhooks