Skip to main content

Forgejo

@thomas/forgejov2026.11.18.2· MIT· 4d agoBEHAVIORS
01README

Administration of a Forgejo (or Gitea) server over its /api/v1 REST API, authenticated with a scoped access token. Find or create organizations and repositories and update their settings; run GitHub pull-mirrors (create via /repos/migrate, reconcile interval, visibility and description, queue immediate syncs); audit every mirror's sync health; manage pull requests (open, inspect mergeability and head CI state, merge); and audit or repoint repository webhooks so a hook pointing at an old CI target is reported. Changes are find-or-create or reversible (archive/unarchive), except the guarded pr_merge. There are no delete methods: an empty repository left by a failed migration is reported, not deleted. Secrets are never output: mirror source credentials are write-only, and webhook operations neither read nor write the hook secret.

02Behaviors1
@thomas/forgejov2026.10.11.1forgejo.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringForgejo base URL, e.g. https://git.example.com (no trailing /api/v1).
tokenstringForgejo access token (Settings → Applications). Supply via vault:
httpTimeoutMs?coerce.numberPer-request timeout (ms) for API calls.
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).
ArgumentTypeDescription
owner?stringRestrict 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(staleFactor?: coerce.number)
Audit every pull-mirror's sync health: last sync, interval, and a
ArgumentTypeDescription
staleFactor?coerce.numberA mirror is stale when its last sync is older than staleFactor × its
fn webhook_audit(owner?: string, name?: string, expectedUrl?: string)
List every repository's webhooks and where they point (factory).
ArgumentTypeDescription
owner?stringRestrict to one org/user's repos. Omit to audit every repo the token
name?stringAudit a single repository. Requires `owner`.
expectedUrl?stringThe 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:
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
urlstringThe URL the matched hook(s) should POST to.
matchUrl?stringSubstring 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/
ArgumentTypeDescription
namestringOrg login name (find-or-create key).
description?stringOrg description to converge.
visibility?enumOrg visibility to converge (Forgejo default: public).
fullName?stringDisplay name to converge.
fn repo_ensure(owner: string, name: string)
Find-or-create a repository under an org or user and converge the
ArgumentTypeDescription
ownerstringOwning org or user login (an org must already exist — see org_ensure).
namestringRepository 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
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
userstringLogin of the user to grant access to.
permission?enumAccess level to converge. A new grant defaults to "write"; when
fn branch_protection_ensure(owner: string, name: string, rule: string)
Find-or-create a branch-protection rule for a branch or glob and
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
rulestringBranch 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
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
fn mirror_ensure(owner: string, name: string, cloneAddr: string, service?: enum, authToken?: string, mirrorInterval?: string, lfs?: boolean, private?: boolean, description?: string)
Find-or-create a pull-mirror of an external repo (GitHub by default)
ArgumentTypeDescription
ownerstringOwning org or user login for the mirror.
namestringMirror repository name (find-or-create key).
cloneAddrstringSource clone URL, e.g. https://github.com/<owner>/<repo>.git
service?enumSource service type (drives metadata migration).
authToken?stringSource-side token for private sources (write-only; sent once to
mirrorInterval?stringPeriodic sync interval as a Go duration (e.g. "8h0m0s"; "0s" disables
lfs?booleanMirror LFS objects too.
private?booleanMirror visibility. Defaults to private on create; when omitted, an
description?stringMirror repo description.
fn mirror_sync_now(owner: string, name: string)
Queue an immediate pull-sync of a mirror (POST /mirror-sync).
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringMirror repository name.
fn pr_list(owner: string, name: string, state?: enum)
List a repository's pull requests with head/base, author and draft
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
state?enumWhich pull requests to list.
fn pr_get(owner: string, name: string, index: coerce.number)
Get one pull request including the server's mergeable verdict and
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
indexcoerce.numberPR number within the repo.
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
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
headstringSource branch. Use owner:branch for a cross-repo (fork) PR.
basestringTarget branch, e.g. main.
titlestringPR title (converged on an existing open PR).
body?stringPR description (converged on an existing open PR).
fn pr_merge(owner: string, name: string, index: coerce.number, strategy?: enum, title?: string, message?: string, deleteBranch?: boolean, force?: boolean)
Merge a pull request. NOT REVERSIBLE — this writes to the base
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
indexcoerce.numberPR number within the repo.
strategy?enumMerge strategy (Forgejo's `Do`).
title?stringMerge commit title override.
message?stringMerge commit message override.
deleteBranch?booleanDelete the head branch after a successful merge.
force?booleanMerge even when the head commit's combined CI state is anything but
fn repo_archive(owner: string, name: string)
Archive a repository (read-only on the server). REVERSIBLE — undo
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
fn repo_unarchive(owner: string, name: string)
Unarchive a repository. REVERSIBLE — undo with repo_archive.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository 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 Versions5
2026.11.18.1MIT(was none)
2026.10.11.1

Added 1 behaviors

2026.09.04.2
2026.09.04.1
2026.06.24.1
04Stats
A
100 / 100
Downloads
44
Archive size
48.7 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
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
05Platforms
06Labels