Skip to main content

Forgejo

@dataverket/forgejov2026.11.15.1· AGPL-3.0-only· 6d agoBEHAVIORSWORKFLOWSEXTENDS
01README

Forgejo (or Gitea) administration for swamp over the /api/v1 REST API with a scoped access token, in the model type @dataverket/forgejo, and the issues of one repository as a stagecraft tracker, @dataverket/forgejo/stagecraft-tracker. 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, a repository's pull-request merge settings (the merge styles offered, the default, update by rebase) read and converged with only the given settings sent, 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. For software factories: a pull request's discussion read back (comments, reviews with their state, inline review comments) and a comment posted on it, a pull request's merge commit, time and merger, issues opened or closed with a comment saying why and an issue's text rewritten (a pull request's number refused before anything is written), a tag protection rule whose whitelists are converged as exact sets, and a @swamp/software-factory work item mirrored one way into a Forgejo issue that is rewritten from the factory's records, commented on when the stage changes or a blocking finding appears, and closed when the work item ends. The second type is a tracker for @swamp/stagecraft, contract version 1, behind stagecraft's publisher: describe, operate with the six operations every tracker offers, and labels, which reports its label scheme; the shipped workflow @dataverket/forgejo-stagecraft-labels writes that scheme with the first type's label_ensure. A ticket is an issue; its status and type are exclusive scoped labels (status/new, type/bug), and the issue's state follows the status. blocked_by is the forge's own issue dependency; parent, related and duplicate relations are kept in a block the tracker owns at the end of both issues' bodies, and the tracker enforces the contract's relation rules itself. It shares the forge client and the label code with the first type, which knows nothing of stagecraft. A second shipped workflow, @dataverket/forgejo-stagecraft-merge-settings, makes a repository a factory works in merge with merge commits only, so the commit a factory recorded reaches the branch as it is. 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. No redirect is followed: a renamed repository's old name is refused with the new name, never read, patched or deleted in its place. Wiki pages: wiki_page_get reads one by its title with its content, and wiki_page_ensure creates it or rewrites it to the content given, leaving a page that already holds those bytes alone; a page is never deleted. Records are stored under portable data names, repo-<owner>-<repo>, pull-<owner>-<repo>-<index>, push-mirror-<owner>-<repo>-<remote> and so on, so they hold on Windows too; before 2026.11.09.1 the names used :, which Windows refuses. Data under an old name is left where it is; the README says how to remove it.

02Behaviors2
@dataverket/forgejov2026.11.15.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.
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?: coerce.boolean, private?: coerce.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?coerce.booleanMirror LFS objects too.
private?coerce.booleanMirror visibility.
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?: coerce.boolean, force?: coerce.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?coerce.booleanDelete the head branch after a successful merge.
force?coerce.booleanMerge even when the head commit's combined CI state is failure/error/
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
@dataverket/forgejo/stagecraft-trackerv2026.11.12.2stagecraft_tracker.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringForgejo base URL, e.g. https://git.example.com (no trailing /api/v1).
tokenstringA token that may read and write the repository's issues. Supply via vault:
httpTimeoutMs?coerce.numberPer-request timeout (ms) for API calls.
ownerstringThe repository's owner.
repostringThe repository whose issues are tickets.
tracker?stringThe tracker's name: the tracker.kind a factory definition names and the
statuses?arrayEach status is a label status/<name> and an issue state. The first is
types?arrayThe ticket types create takes, each a label type/<name>.
severities?arraySeverity labels severity/<name> in the scheme labels reports, mildest first.
fn describe()
Say what this tracker is: its name, contract 1, origin snapshot, no optional capabilities.
fn operate(operation: string, request: union, answer: string, run?: string)
Make one tracker operation on the repository's issues and write its answer (the result, or the failure)
ArgumentTypeDescription
operationstringThe operation: fetch_issue, create, comment, set_status, relate or unrelate
requestunionThe operation's request: an object, or a JSON object as a string
answerstringThe record to write the answer under (answer-...)
run?stringThe run asking, recorded with the answer
fn labels()
Record the tracker's label scheme (status/, type/ and severity/ labels, exclusive) from its settings,

Resources

answer(infinite)— operate's answers: each operation's result or failure, under the name the caller gave
description(infinite)— What the tracker says of itself: its name, contract version and capabilities
trackerLabels(infinite)— The tracker's label scheme from its settings, in the form the base type's label_ensure takes
03Workflows2
@dataverket/forgejo-stagecraft-labels5a8da8d5-7458-4310-bf2d-66e1dbf4c394

Converge a repository's labels to its stagecraft tracker's settings: one label status/<name>, type/<name> and severity/<name> for each status, type and severity of the @dataverket/forgejo/stagecraft-tracker instance named, scoped and exclusive, so an issue carries one of each. The tracker only reports its scheme (labels); the labels are written by the @dataverket/forgejo instance named, with its label_ensure, which reads first, creates what is missing, corrects a colour or a description that dif

labelsThe tracker's label scheme, written through the base type
1.scheme${{ inputs.tracker }}.labels— The tracker records its label scheme from its settings; no forge call.
2.labels-ensure${{ inputs.forgejo }}.label_ensure— Create or correct those labels on the tracker's repository; keep the rest; delete nothing.
@dataverket/forgejo-stagecraft-merge-settings2b798979-97bc-4421-8c04-d538d5b5917d

Make a repository that a stagecraft factory works in merge pull requests with merge commits only, so the commit a factory recorded (a review, a signature, an attestation tag) reaches the branch as it is. Merge commits are on and the default; fast-forward, rebase, rebase with a merge commit, squash and update by rebase are off: a rebase or a squash can make new commits, an update by rebase rewrites the pull request's head, and fast-forward works only for the first of several parallel branches, th

merge-settingsThe merge settings read, converged and read back, then the branch rule.
1.before${{ inputs.forgejo }}.repo_merge_settings_ensure— The repository's merge settings as they are, read and recorded before anything changes.
2.merge-commits-only${{ inputs.forgejo }}.repo_merge_settings_ensure— Merge commits on and the default; fast-forward, rebase, rebase with a merge commit, squash and update by rebase off. Only the settings that differ are sent, and the forge's answer is checked.
3.merge-commits-only-in-force— The forge reports the seven settings, read back after the write.
4.protection-rules${{ inputs.forgejo }}.branch_protection_list— The repository's branch protection rules, read, so the next step sees the rule as it is now.
5.no-outdated-branch-block${{ inputs.forgejo }}.branch_protection_ensure— The branch's rule stops requiring an up-to-date branch, that field alone sent. Skipped when the rule does not require it, and when this run's list did not record it (no rule, or only an older record), so no rule is created here.
6.no-outdated-branch-block-in-force— The branch's rule, if there is one, does not require an up-to-date branch.
04Extends17
@dataverket/forgejoactions.ts
fn runner_list(owner: string, repo?: string)
List the Actions runners visible to a repository or an organization, with status and labels (factory).
ArgumentTypeDescription
ownerstringOrg login (org scope) or repo owner.
repo?stringRepository name to list the runners visible to that repository; omit for the org's.
fn runner_prune(owner: string, repo?: string, name: string)
Delete every offline Actions runner with a given name at a repository or an organization (factory).
ArgumentTypeDescription
ownerstringOrg login (org scope) or repo owner.
repo?stringRepository name for repo-scoped runners; omit for the org's.
namestringRunner name whose offline registrations are deleted.
fn actions_secret_put(owner: string, repo?: string, name: string, value: string)
Create or update an Actions secret on a repository or an organization. Write-only: the value comes
ArgumentTypeDescription
ownerstringOrg login (org-scoped secret) or repo owner.
repo?stringRepository name for a repo-scoped secret; omit for an org-scoped one.
namestringSecret name as the workflow reads it, e.g. COSIGN_PRIVATE_KEY.
valuestringSecret value. Supply via vault: ${{ vault.get('<vault>', '<key>') }} — quoted, which is the spelling swamp model validate recognizes. Never recorded.
fn repo_rename(owner: string, name: string, newName: string)
Rename a repository. Verify-first: the source must exist and no repository may already hold the new
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringCurrent repository name.
newNamestringNew repository name. Forgejo keeps a redirect from the old name until it is reused.
fn runner_registration_token(owner: string, repo?: string)
Fetch a registration token for a repository or organization runner, for `forgejo-runner register`
ArgumentTypeDescription
ownerstringOrg login (org-wide runner) or repo owner.
repo?stringRepository name for a repo-scoped runner; omit for an org-wide one.

Resources

actionsSecret(infinite)— An Actions secret's name and scope. Never the value.
runnerRegistration(infinite)— A runner registration token, stored in the repository's default vault; the record holds a reference.
runnerPrune(infinite)— Offline runners of one name deleted at a scope, and the live ones kept.
runner(infinite)— A registered Actions runner: name, online/offline status, labels, and scope.
repoRename(infinite)— A repository rename: old and new name and the URLs that changed.
@dataverket/forgejochecks.ts
@dataverket/forgejopush_mirror.ts
fn push_mirror_ensure(owner: string, name: string, remoteAddress: string, remoteUsername?: string, remotePassword: string, interval?: string, syncOnCommit?: boolean, branchFilter?: string, syncNow?: boolean)
Find-or-create a push mirror of a repository to a remote (GitHub, for instance). The remote token comes
ArgumentTypeDescription
ownerstringOwning org or user login on Forgejo.
namestringRepository name on Forgejo.
remoteAddressstringHTTPS clone URL to push to, e.g. https://github.com/<org>/<repo>.git
remoteUsername?stringUsername sent with the token; GitHub accepts any non-empty value for a PAT.
remotePasswordstringToken for the remote. Supply via vault: ${{ vault.get('<vault>', '<key>') }} — quoted, which is the spelling swamp model validate recognizes. Sent once to Forgejo, never recorded.
interval?stringPeriodic push interval as a Go duration; 0s disables periodic pushes.
syncOnCommit?booleanPush on every commit.
branchFilter?stringGlob of branches to push; empty pushes everything.
syncNow?booleanQueue an immediate push after creating the mirror.
fn push_mirror_list(owner: string, name?: string)
Audit the push mirrors of one repository or of every repository of an org or user (factory): remote,
ArgumentTypeDescription
ownerstringOrg or user login whose repositories to audit.
name?stringOne repository; omit to audit every repository of the owner.
fn push_mirror_delete(owner: string, name: string, remoteAddress: string)
Delete the push mirror of a repository to one remote address (no-op when absent). Forgejo stops
ArgumentTypeDescription
ownerstringOwning org or user login on Forgejo.
namestringRepository name on Forgejo.
remoteAddressstringRemote address of the mirror to delete.
fn push_mirror_sync_now(owner: string, name: string)
Queue an immediate push of every push mirror of a repository. Additive; changes no settings.
ArgumentTypeDescription
ownerstring
namestring

Resources

pushMirrorDelete(infinite)— A push mirror deletion: which remote was removed from which repository.
pushMirror(infinite)— A push mirror of a repository: remote address, timing, last push and last error. Never the credential.
@dataverket/forgejopull_mirror.ts
fn pull_mirror_ensure(owner: string, name: string, cloneAddr: string, private?: boolean, interval?: string, description?: string, lfs?: boolean, service?: enum, authToken?: string)
Find-or-create a pull mirror of an external repository. Sends only the settings given: a new mirror gets
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. Fixed once the mirror exists.
private?booleanMirror visibility. Unset: a new mirror gets Forgejo's default (public unless the instance forces private) and an existing one keeps its own.
interval?stringPeriodic sync interval as a Go duration; 0s disables it. Unset: the forge's default, or the mirror's own.
description?stringRepository description. Unset: none on create, unchanged after.
lfs?booleanMirror LFS objects too. Only used on create; unset is the forge's default.
service?enumSource service type, for the migration. Only used on create; unset is the forge's default.
authToken?stringToken for a private source. Supply via vault: ${{ vault.get('<vault>', '<key>') }}. Sent once to Forgejo on create, never recorded.

Resources

pullMirror(infinite)— A pull mirror after pull_mirror_ensure: source, visibility, interval, last sync, and what changed.
@dataverket/forgejotopics.ts
fn repo_topics_ensure(owner: string, name: string, topics: array, exact?: boolean)
Ensure a repository has the given topics (Forgejo's repository labels). Additive by default; exact=true
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
topicsarrayTopics the repository must have, e.g. ["upstream-mirror"]. Lowercased before use.
exact?booleanMake the list the whole set, removing any other topic. Off: other topics are kept.

Resources

repoTopics(infinite)— A repository's topics after repo_topics_ensure, and which were added or removed.
@dataverket/forgejounits.ts
fn repo_units_ensure(owner: string, name: string, hasActions?: boolean, hasPackages?: boolean, hasProjects?: boolean)
Switch a repository's Actions, packages or projects unit on or off; the units repo_ensure does not reach.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
hasActions?booleanForgejo Actions on the repository, so its .forgejo/workflows run.
hasPackages?booleanThe package registry unit.
hasProjects?booleanThe projects (boards) unit.

Resources

repoUnits(infinite)— A repository's Actions, packages and projects units after repo_units_ensure, and which changed.
@dataverket/forgejomerge_settings.ts
fn repo_merge_settings_ensure(owner: string, name: string, allowMergeCommits?: boolean, allowRebase?: boolean, allowRebaseExplicit?: boolean, allowSquashMerge?: boolean, allowFastForwardOnlyMerge?: boolean, allowRebaseUpdate?: boolean, defaultMergeStyle?: enum, defaultUpdateStyle?: enum, defaultDeleteBranchAfterMerge?: boolean, defaultAllowMaintainerEdit?: boolean, ignoreWhitespaceConflicts?: boolean)
Read or converge a repository's pull-request merge settings: the merge styles offered, the default style,
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
allowMergeCommits?booleanOffer merging with a merge commit.
allowRebase?booleanOffer rebase-merging, which makes new commits.
allowRebaseExplicit?booleanOffer rebase followed by a merge commit (--no-ff); the rebase makes new commits.
allowSquashMerge?booleanOffer squash-merging, which makes one new commit.
allowFastForwardOnlyMerge?booleanOffer fast-forward-only merging, which keeps the branch's commits.
allowRebaseUpdate?booleanOffer updating a pull request's branch by rebase, which rewrites its head.
defaultMergeStyle?enumThe style the merge button uses when no other is chosen.
defaultUpdateStyle?enumThe style the update-branch button uses when no other is chosen.
defaultDeleteBranchAfterMerge?booleanDelete a pull request's branch after merge, by default.
defaultAllowMaintainerEdit?booleanLet maintainers edit a new pull request's branch, by default.
ignoreWhitespaceConflicts?booleanIgnore whitespace when checking a pull request for conflicts.

Resources

repoMergeSettings(infinite)— A repository's pull-request merge settings after repo_merge_settings_ensure, and which changed.
@dataverket/forgejopr_assign.ts
fn user_search(q: string)
Search forge users by login or name fragment, without admin scope; the way to find a login for pr_assign. Read-only.
ArgumentTypeDescription
qstringLogin or name fragment to search for.
fn pr_assign(owner: string, name: string, index: number, assignees: array)
Assign a pull request to one or more logins, replacing the current assignees. Every login is
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
indexnumberPR number within the repo.
assigneesarrayLogins to assign; replaces the current list. Each must exist on the forge.

Resources

prAssignment(infinite)— A pull request's assignees after pr_assign, as Forgejo reports them.
userMatch(7d)— A user matched by user_search: login and full name.
@dataverket/forgejorepo_delete.ts
fn repo_delete(owner: string, name: string, allowContent?: boolean)
Delete a repository (no-op when absent). Verify-first: the repository is read, and one with commits is
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
allowContent?booleanDelete even when the repository has commits. Off by default: Forgejo has no undelete.

Resources

repoDelete(infinite)— A repository deletion by repo_delete: what it was and what happened.
@dataverket/forgejoorg_delete.ts
fn org_delete(name: string)
Delete an organization (no-op when absent). Verify-first: the organization is read, and one that still
ArgumentTypeDescription
namestringOrg login name.

Resources

orgDelete(infinite)— An organization deletion by org_delete: what it was and what happened.
@dataverket/forgejoissues.ts
fn issue_state_ensure(owner: string, name: string, issues: array)
Open or close the issues given, each with a comment saying why. Several in one call.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
issuesarrayThe issues and the state each is to have. Several in one call.
fn issue_body_ensure(owner: string, name: string, number: number, body: string)
Give one issue the text given, replacing what is there. An issue that already has it is left alone;
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
numbernumberThe issue's number.
bodystringThe issue's whole text, in Markdown. It replaces the text that is there.
fn issue_ensure(owner: string, name: string, issues: array)
File the issues given, each unless an issue of the same exact title exists, open or closed.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
issuesarrayThe issues to file. One with an existing issue's exact title, open or closed, is left as it is.
fn issue_labels_ensure(owner: string, name: string, number: number, labels: array, exact?: boolean)
Ensure an issue or pull request carries the given labels, by name; additive unless exact.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
numbernumberThe issue's or pull request's number; Forgejo numbers both in one sequence.
labelsarrayLabel names it must carry; each must exist on the repository or its organization.
exact?booleanMake the list the whole set, removing any other label. Off: other labels are kept.
fn issue_list(owner: string, name: string, state?: enum)
The issues of a repository in the given state, every page, pull requests excluded. Read-only.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
state?enumWhich issues to list.

Resources

issueState(infinite)— An issue's state as issue_state_ensure last set or found it.
issueBody(infinite)— Whether issue_body_ensure last rewrote an issue's text or found it as given. The text is not kept.
issue(infinite)— One issue of a repository: number, title, state and page, and whether issue_ensure created it or found it.
issueLabels(infinite)— An issue's or pull request's labels after issue_labels_ensure, and which were added or removed.
@dataverket/forgejolabels.ts
fn label_ensure(owner: string, name?: string, labels: array, prune?: boolean)
Ensure the labels of an organization, or of one repository: create what is missing, patch what differs
ArgumentTypeDescription
ownerstringThe organization, or a repository's owner.
name?stringRepository name. Absent: the organization's labels, shared by all its repositories.
labelsarray
prune?booleanDelete every label of this scope that is not in the list.
fn label_list(owner: string, name?: string)
The labels of an organization, or of one repository, every page. Read-only.
ArgumentTypeDescription
ownerstringThe organization, or a repository's owner.
name?stringRepository name. Absent: the organization's labels.

Resources

label(infinite)— One label of an organization or a repository: id, name, color, description, exclusivity, and what label_ensure did to it.
@dataverket/forgejopr_comment.ts
fn pr_feedback()
Read a pull request's discussion from the server: comments, reviews (with state) and inline review comments. Read-only.
fn pr_comment(body: string)
Post a comment on a pull request. Not idempotent: every call posts a new comment.
ArgumentTypeDescription
bodystringComment text (Markdown).

Resources

prFeedback(infinite)— Comments, reviews and inline review comments on a pull request.
prComment(infinite)— A comment posted on a pull request.
@dataverket/forgejopr_merge_state.ts
fn pr_merge_state(owner: string, name: string, index: coerce.number)
Read a pull request's merge state from the server: its head, and once merged the merge commit, time and merger. Read-only.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
indexcoerce.numberPR number within the repo.

Resources

prMergeState(infinite)— A pull request's head and, once merged, its merge commit, time, and merger.
@dataverket/forgejowork_item_sync.ts
fn work_item_sync(owner: string, name: string, factory: string, workItem: string, issue?: coerce.number)
Mirror a software-factory work item into its Forgejo issue: create or adopt the issue, rewrite its body from the factory's records, comment on stage changes and new blocking findings, and close it when the work item is done or aborted. Idempotent apart from those comments.
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
factorystringThe @swamp/software-factory model that runs the work item.
workItemstringThe work item to mirror.
issue?coerce.numberAdopt this existing issue on the first sync instead of creating one (0: create one). Ignored once the work item is linked.

Resources

workItemIssue(infinite)— The Forgejo issue a factory work item is mirrored into.
@dataverket/forgejotag_protection.ts
fn tag_protection_ensure(owner: string, name: string, namePattern: string, whitelistUsernames?: array, whitelistTeams?: array)
Find-or-create a tag protection rule for a tag glob and converge who may push matching tags,
ArgumentTypeDescription
ownerstringOwning org or user login.
namestringRepository name.
namePatternstringTag glob the rule applies to (find-or-create key), e.g. attestation/*.
whitelistUsernames?arrayLogins allowed to create or delete matching tags. Converged as an exact set; empty means nobody.
whitelistTeams?arrayOrg teams allowed to create or delete matching tags. Converged as an exact set.

Resources

tagProtection(infinite)— A tag protection rule: the pattern and who may push matching tags.
@dataverket/forgejowiki.ts
fn wiki_page_get()
Read one wiki page of a repository by its title, with its markdown content and last commit. Read-only.
fn wiki_page_ensure(content: string, message?: string)
Create a wiki page or rewrite it to the content given; a page already holding that content is left alone.
ArgumentTypeDescription
contentstringThe whole page, markdown, UTF-8. On the CLI, @<path> reads it from a file: --input content=@page.md
message?stringThe wiki commit message. Default: 'Add <title>' or 'Update <title>'.

Resources

wikiPage(infinite)— A wiki page after wiki_page_get (with its content) or wiki_page_ensure (what changed).
05Previous Versions15
2026.11.12.2AGPL-3.0-only

Added 1 workflows

2026.11.12.1AGPL-3.0-only

Added 1 behaviors. Added 1 workflows

2026.11.11.1AGPL-3.0-only
2026.11.09.1AGPL-3.0-only
2026.10.27.1AGPL-3.0-only(was none)
2026.10.26.1
2026.10.05.4
2026.10.05.3

Added 1 behaviors. updated labels

2026.10.05.2
2026.10.05.1

updated labels

2026.10.04.2
2026.10.04.1
2026.09.30.1

updated labels

2026.09.29.2
2026.09.29.1
06Stats
A
100 / 100
Downloads
69
Archive size
163.1 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
07Platforms
08Labels