Forgejo
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.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Forgejo base URL, e.g. https://git.example.com (no trailing /api/v1). |
| token | string | Forgejo access token (Settings → Applications). Supply via vault: |
| httpTimeoutMs? | coerce.number | Per-request timeout (ms) for API calls. |
| Argument | Type | Description |
|---|---|---|
| owner? | string | Restrict to one org/user's repos. Omit to list every repo the token |
| Argument | Type | Description |
|---|---|---|
| staleFactor? | coerce.number | A mirror is stale when its last sync is older than staleFactor × its |
| Argument | Type | Description |
|---|---|---|
| owner? | string | Restrict to one org/user's repos. Omit to audit every repo the token |
| name? | string | Audit a single repository. Requires `owner`. |
| expectedUrl? | string | The URL every hook is supposed to point at. Supplying it populates |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| url | string | The URL the matched hook(s) should POST to. |
| matchUrl? | string | Substring identifying WHICH hook to repoint (matched against the |
| Argument | Type | Description |
|---|---|---|
| name | string | Org login name (find-or-create key). |
| description? | string | Org description to converge. |
| visibility? | enum | Org visibility to converge (Forgejo default: public). |
| fullName? | string | Display name to converge. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login (an org must already exist — see org_ensure). |
| name | string | Repository name (find-or-create key). |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| user | string | Login of the user to grant access to. |
| permission? | enum | Access level to converge. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| rule | string | Branch name or glob the rule applies to (find-or-create key), e.g. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login for the mirror. |
| name | string | Mirror repository name (find-or-create key). |
| cloneAddr | string | Source clone URL, e.g. https://github.com/<owner>/<repo>.git |
| service? | enum | Source service type (drives metadata migration). |
| authToken? | string | Source-side token for private sources (write-only; sent once to |
| mirrorInterval? | string | Periodic sync interval as a Go duration (e.g. "8h0m0s"; "0s" disables |
| lfs? | coerce.boolean | Mirror LFS objects too. |
| private? | coerce.boolean | Mirror visibility. |
| description? | string | Mirror repo description. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Mirror repository name. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| state? | enum | Which pull requests to list. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| index | coerce.number | PR number within the repo. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| head | string | Source branch. Use owner:branch for a cross-repo (fork) PR. |
| base | string | Target branch, e.g. main. |
| title | string | PR title (converged on an existing open PR). |
| body? | string | PR description (converged on an existing open PR). |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| index | coerce.number | PR number within the repo. |
| strategy? | enum | Merge strategy (Forgejo's `Do`). |
| title? | string | Merge commit title override. |
| message? | string | Merge commit message override. |
| deleteBranch? | coerce.boolean | Delete the head branch after a successful merge. |
| force? | coerce.boolean | Merge even when the head commit's combined CI state is failure/error/ |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Forgejo base URL, e.g. https://git.example.com (no trailing /api/v1). |
| token | string | A token that may read and write the repository's issues. Supply via vault: |
| httpTimeoutMs? | coerce.number | Per-request timeout (ms) for API calls. |
| owner | string | The repository's owner. |
| repo | string | The repository whose issues are tickets. |
| tracker? | string | The tracker's name: the tracker.kind a factory definition names and the |
| statuses? | array | Each status is a label status/<name> and an issue state. The first is |
| types? | array | The ticket types create takes, each a label type/<name>. |
| severities? | array | Severity labels severity/<name> in the scheme labels reports, mildest first. |
| Argument | Type | Description |
|---|---|---|
| operation | string | The operation: fetch_issue, create, comment, set_status, relate or unrelate |
| request | union | The operation's request: an object, or a JSON object as a string |
| answer | string | The record to write the answer under (answer-...) |
| run? | string | The run asking, recorded with the answer |
Resources
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
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
| Argument | Type | Description |
|---|---|---|
| owner | string | Org login (org scope) or repo owner. |
| repo? | string | Repository name to list the runners visible to that repository; omit for the org's. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Org login (org scope) or repo owner. |
| repo? | string | Repository name for repo-scoped runners; omit for the org's. |
| name | string | Runner name whose offline registrations are deleted. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Org login (org-scoped secret) or repo owner. |
| repo? | string | Repository name for a repo-scoped secret; omit for an org-scoped one. |
| name | string | Secret name as the workflow reads it, e.g. COSIGN_PRIVATE_KEY. |
| value | string | Secret value. Supply via vault: ${{ vault.get('<vault>', '<key>') }} — quoted, which is the spelling swamp model validate recognizes. Never recorded. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Current repository name. |
| newName | string | New repository name. Forgejo keeps a redirect from the old name until it is reused. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Org login (org-wide runner) or repo owner. |
| repo? | string | Repository name for a repo-scoped runner; omit for an org-wide one. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login on Forgejo. |
| name | string | Repository name on Forgejo. |
| remoteAddress | string | HTTPS clone URL to push to, e.g. https://github.com/<org>/<repo>.git |
| remoteUsername? | string | Username sent with the token; GitHub accepts any non-empty value for a PAT. |
| remotePassword | string | Token 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? | string | Periodic push interval as a Go duration; 0s disables periodic pushes. |
| syncOnCommit? | boolean | Push on every commit. |
| branchFilter? | string | Glob of branches to push; empty pushes everything. |
| syncNow? | boolean | Queue an immediate push after creating the mirror. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Org or user login whose repositories to audit. |
| name? | string | One repository; omit to audit every repository of the owner. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login on Forgejo. |
| name | string | Repository name on Forgejo. |
| remoteAddress | string | Remote address of the mirror to delete. |
| Argument | Type | Description |
|---|---|---|
| owner | string | |
| name | string |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login for the mirror. |
| name | string | Mirror repository name (find-or-create key). |
| cloneAddr | string | Source clone URL, e.g. https://github.com/<owner>/<repo>.git. Fixed once the mirror exists. |
| private? | boolean | Mirror visibility. Unset: a new mirror gets Forgejo's default (public unless the instance forces private) and an existing one keeps its own. |
| interval? | string | Periodic sync interval as a Go duration; 0s disables it. Unset: the forge's default, or the mirror's own. |
| description? | string | Repository description. Unset: none on create, unchanged after. |
| lfs? | boolean | Mirror LFS objects too. Only used on create; unset is the forge's default. |
| service? | enum | Source service type, for the migration. Only used on create; unset is the forge's default. |
| authToken? | string | Token for a private source. Supply via vault: ${{ vault.get('<vault>', '<key>') }}. Sent once to Forgejo on create, never recorded. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| topics | array | Topics the repository must have, e.g. ["upstream-mirror"]. Lowercased before use. |
| exact? | boolean | Make the list the whole set, removing any other topic. Off: other topics are kept. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| hasActions? | boolean | Forgejo Actions on the repository, so its .forgejo/workflows run. |
| hasPackages? | boolean | The package registry unit. |
| hasProjects? | boolean | The projects (boards) unit. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| allowMergeCommits? | boolean | Offer merging with a merge commit. |
| allowRebase? | boolean | Offer rebase-merging, which makes new commits. |
| allowRebaseExplicit? | boolean | Offer rebase followed by a merge commit (--no-ff); the rebase makes new commits. |
| allowSquashMerge? | boolean | Offer squash-merging, which makes one new commit. |
| allowFastForwardOnlyMerge? | boolean | Offer fast-forward-only merging, which keeps the branch's commits. |
| allowRebaseUpdate? | boolean | Offer updating a pull request's branch by rebase, which rewrites its head. |
| defaultMergeStyle? | enum | The style the merge button uses when no other is chosen. |
| defaultUpdateStyle? | enum | The style the update-branch button uses when no other is chosen. |
| defaultDeleteBranchAfterMerge? | boolean | Delete a pull request's branch after merge, by default. |
| defaultAllowMaintainerEdit? | boolean | Let maintainers edit a new pull request's branch, by default. |
| ignoreWhitespaceConflicts? | boolean | Ignore whitespace when checking a pull request for conflicts. |
Resources
| Argument | Type | Description |
|---|---|---|
| q | string | Login or name fragment to search for. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| index | number | PR number within the repo. |
| assignees | array | Logins to assign; replaces the current list. Each must exist on the forge. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| allowContent? | boolean | Delete even when the repository has commits. Off by default: Forgejo has no undelete. |
Resources
| Argument | Type | Description |
|---|---|---|
| name | string | Org login name. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| issues | array | The issues and the state each is to have. Several in one call. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| number | number | The issue's number. |
| body | string | The issue's whole text, in Markdown. It replaces the text that is there. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| issues | array | The issues to file. One with an existing issue's exact title, open or closed, is left as it is. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| number | number | The issue's or pull request's number; Forgejo numbers both in one sequence. |
| labels | array | Label names it must carry; each must exist on the repository or its organization. |
| exact? | boolean | Make the list the whole set, removing any other label. Off: other labels are kept. |
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| state? | enum | Which issues to list. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | The organization, or a repository's owner. |
| name? | string | Repository name. Absent: the organization's labels, shared by all its repositories. |
| labels | array | |
| prune? | boolean | Delete every label of this scope that is not in the list. |
| Argument | Type | Description |
|---|---|---|
| owner | string | The organization, or a repository's owner. |
| name? | string | Repository name. Absent: the organization's labels. |
Resources
| Argument | Type | Description |
|---|---|---|
| body | string | Comment text (Markdown). |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| index | coerce.number | PR number within the repo. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| factory | string | The @swamp/software-factory model that runs the work item. |
| workItem | string | The work item to mirror. |
| issue? | coerce.number | Adopt this existing issue on the first sync instead of creating one (0: create one). Ignored once the work item is linked. |
Resources
| Argument | Type | Description |
|---|---|---|
| owner | string | Owning org or user login. |
| name | string | Repository name. |
| namePattern | string | Tag glob the rule applies to (find-or-create key), e.g. attestation/*. |
| whitelistUsernames? | array | Logins allowed to create or delete matching tags. Converged as an exact set; empty means nobody. |
| whitelistTeams? | array | Org teams allowed to create or delete matching tags. Converged as an exact set. |
Resources
| Argument | Type | Description |
|---|---|---|
| content | string | The whole page, markdown, UTF-8. On the CLI, @<path> reads it from a file: --input content=@page.md |
| message? | string | The wiki commit message. Default: 'Add <title>' or 'Update <title>'. |
Resources
Added 1 workflows
Added 1 behaviors. Added 1 workflows
Added 1 behaviors. updated labels
updated labels
updated labels
- 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