Forgejo

@shrug/forgejov2026.09.29.2· 1mo agoBEHAVIORS

01README

Drive Forgejo and Gitea instances from swamp over their shared /api/v1 REST surface, authenticated with a personal access token — a swamp node for a self-hosted git forge with read and confirm-gated write paths.

Every method persists a typed, CEL-referenceable snapshot. Per-repo snapshots are keyed owner__repo (single issues/PRs add __<index>):

data.latest("forgejo", "acme__infra").attributes.issues
data.latest("forgejo", "testuser__demo__12").attributes

Methods

Read: list_repos, get_repo, list_issues (pins type=issues, so pull requests are excluded; filter open/closed/all), get_issue, list_pulls, get_pull (populates additions/deletions/changed_files the list endpoint omits), list_releases, list_deploy_keys, list_orgs, list_org_repos, list_org_teams, list_collaborators, get_user, list_labels (excludes org-level labels), list_milestones.

Write (all confirm-gated): create_repo, create_org_repo, edit_repo, delete_repo, create_deploy_key, add_collaborator, remove_collaborator, add_org_team_member, create_issue (labels are numeric IDs; milestone is a numeric ID), edit_issue (milestone set / clear_milestone unset; assignees replace/clear), create_issue_comment, add_issue_labels, create_pull (open a PR head->base; optional labels/milestone/assignees), create_label, create_milestone, create_user (site-admin token).

Label names and milestone titles are not unique in Forgejo/Gitea, and the issue API expects label/milestone IDs — resolve IDs from a list_labels / list_milestones snapshot via CEL before creating/associating.

Security

token is a sensitive global argument — wire it from a vault at model-create time, never inline it.
The token is sent as an Authorization: token … header and is never logged.
Every mutating method is confirm-gated (confirm=true required) and every caller-supplied path segment is percent-encoded.

Quickstart

swamp vault put forgejo token           # hidden prompt
swamp model create @shrug/forgejo forgejo \
  --global-arg host=https://git.example.org \
  --global-arg token='${{ vault.get(forgejo, token) }}'

swamp model method run forgejo list_repos
swamp model method run forgejo list_issues --arg owner=acme --arg repo=infra

Known limitations

List methods expose page / limit but do not auto-paginate.
No rate-limit backoff: a 429 throws immediately.
No Projects API: Gitea 1.27.x exposes no /projects surface, so no project/board method ships.
Bare creates (create_deploy_key/create_label/create_milestone) are not idempotent — verify-first with the matching list_* (the caller's job).
create_pull opens PRs, but there is no merge_pull or reviewer-request path yet; no label/milestone edit/delete surface yet.

02Behaviors1

@shrug/forgejov2026.09.29.2forgejo.ts

Global Arguments

Argument	Type	Required	Description
host	string	yes	Forgejo or Gitea instance URL (e.g. https://codeberg.org). No trailing slash.
token	string	yes	Personal access token for the Forgejo/Gitea instance.
metadata	record	yes

fn list_repos()

List repositories owned by or accessible to the authenticated user.

fn get_repo(owner: string, repo: string)

Get details for a specific repository.

Argument	Type	Required	Description
owner	string	yes	Repository owner (user or org login).
repo	string	yes	Repository name.

fn list_issues(state: enum)

List issues for a repository.

Argument	Type	Required	Description
state	enum	yes	Filter by issue state.

fn get_issue(index: number)

Get a specific issue by number.

Argument	Type	Required	Description
index	number	yes	Issue number.

fn list_pulls(state: enum)

List pull requests for a repository.

Argument	Type	Required	Description
state	enum	yes	Filter by pull request state.

fn get_pull(index: number)

Get a specific pull request by number.

Argument	Type	Required	Description
index	number	yes	Pull request number.

fn list_releases()

List releases for a repository.

fn list_deploy_keys()

List deploy keys registered on a repository (verify-first before create).

fn create_deploy_key(title: string, key: string, read_only: boolean)

Argument	Type	Required	Description
title	string	yes	Human-readable label for the deploy key.
key	string	yes	Public key material, e.g. 'ssh-ed25519 AAAA...'.
read_only	boolean	yes	Grant read-only access (true, default) or read/write (false).

fn create_repo(name: string, description: string, private: boolean, auto_init: boolean, default_branch: string, confirm: boolean)

Create a repository owned by the authenticated user (POST /user/repos). Confirm-gated (a live mutation). Push existing history afterwards, or set auto_init to seed an initial commit.

Argument	Type	Required	Description
name	string	yes	Repository name.
description	string	yes	Repository description.
private	boolean	yes	Whether the repository is private (default false — public, anonymously cloneable).
auto_init	boolean	yes	Initialize with an initial commit (README). Leave false to push an existing history.
default_branch	string	yes	Default branch name.
confirm	boolean	yes	Must be true to create the repository — this is a live mutation.

fn create_org_repo(org: string, name: string, description: string, private: boolean, auto_init: boolean, default_branch: string, confirm: boolean)

Create a repository owned by an organization (POST /orgs/{org}/repos). Confirm-gated (a live mutation).

Argument	Type	Required	Description
org	string	yes	Organization login that will own the repository.
name	string	yes	Repository name.
description	string	yes	Repository description.
private	boolean	yes	Whether the repository is private (default false).
auto_init	boolean	yes	Initialize with an initial commit (README). Leave false to push an existing history.
default_branch	string	yes	Default branch name.
confirm	boolean	yes	Must be true to create the repository — this is a live mutation.

fn edit_repo(private?: boolean, description?: string, default_branch?: string, archived?: boolean, confirm: boolean)

Edit a repository's settings (PATCH /repos/{owner}/{repo}). Only provided fields are sent. Confirm-gated (a live mutation).

Argument	Type	Required	Description
private?	boolean	no	Set the repository private (true) or public (false). Omit to leave unchanged.
description?	string	no	New description. Omit to leave unchanged.
default_branch?	string	no	New default branch. Omit to leave unchanged.
archived?	boolean	no	Archive (true) or unarchive (false) the repository. Omit to leave unchanged.
confirm	boolean	yes	Must be true to edit the repository — this is a live mutation.

fn delete_repo(confirm: boolean)

Delete a repository (DELETE /repos/{owner}/{repo}). Destructive and confirm-gated: the driver should get_repo first to verify the target (Rule 5). No snapshot is written.

Argument	Type	Required	Description
confirm	boolean	yes	Must be true to delete the repository — this is a destructive live mutation.

fn list_orgs()

List organizations the authenticated user belongs to (GET /user/orgs).

fn list_org_repos(org: string)

List repositories owned by an organization (GET /orgs/{org}/repos).

Argument	Type	Required	Description
org	string	yes	Organization login.

fn get_user(username: string)

Get a user account by login (GET /users/{username}).

Argument	Type	Required	Description
username	string	yes	User login.

fn list_collaborators()

List collaborators on a repository (GET /repos/{owner}/{repo}/collaborators). Verify-first before add.

fn add_collaborator(username: string, confirm: boolean)

Add or update a collaborator on a repository (PUT /repos/{owner}/{repo}/collaborators/{username}). Defaults to write permission (least privilege). Confirm-gated (a live mutation).

Argument	Type	Required	Description
username	string	yes	User to add as a collaborator.
confirm	boolean	yes	Must be true to add the collaborator — this is a live mutation.

fn remove_collaborator(username: string, confirm: boolean)

Remove a collaborator from a repository (DELETE /repos/{owner}/{repo}/collaborators/{username}). Confirm-gated (a live mutation). No snapshot is written.

Argument	Type	Required	Description
username	string	yes	Collaborator to remove.
confirm	boolean	yes	Must be true to remove the collaborator — this is a live mutation.

fn list_org_teams(org: string)

List teams within an organization (GET /orgs/{org}/teams).

Argument	Type	Required	Description
org	string	yes	Organization login.

fn add_org_team_member(team_id: number, username: string, confirm: boolean)

Add a user to a team (PUT /teams/{team_id}/members/{username}). Confirm-gated (a live mutation).

Argument	Type	Required	Description
team_id	number	yes	Team ID.
username	string	yes	User to add to the team.
confirm	boolean	yes	Must be true to add the team member — this is a live mutation.

fn create_issue(title: string, body: string, labels?: array, milestone?: number, assignees?: array, confirm: boolean)

Create an issue in a repository (POST /repos/{owner}/{repo}/issues). Confirm-gated (a live mutation).

Argument	Type	Required	Description
title	string	yes	Issue title.
body	string	yes	Issue body (markdown).
labels?	array	no	Label IDs to apply (Forgejo's issue API expects IDs, not names — resolve names to IDs from a list_labels snapshot). Omit to apply none.
milestone?	number	no	Milestone ID to associate (resolve from a list_milestones snapshot). Omit for none.
assignees?	array	no	Usernames to assign. Omit to assign none.
confirm	boolean	yes	Must be true to create the issue — this is a live mutation.

fn edit_issue(index: number, title?: string, body?: string, state?: enum, milestone?: number, clear_milestone?: boolean, assignees?: array, confirm: boolean)

Edit an issue (PATCH /repos/{owner}/{repo}/issues/{index}). Only provided fields are sent; set state to open/closed to reopen/close. Confirm-gated (a live mutation).

Argument	Type	Required	Description
index	number	yes	Issue number.
title?	string	no	New title. Omit to leave unchanged.
body?	string	no	New body. Omit to leave unchanged.
state?	enum	no	New state (open/closed). Omit to leave unchanged.
milestone?	number	no	Set the milestone to this ID. Omit to leave unchanged (use clear_milestone to unset).
clear_milestone?	boolean	no	Unset the issue's milestone (sends milestone=0). Mutually exclusive with milestone.
assignees?	array	no	Replace the issue's assignees with these usernames. Omit to leave unchanged; pass [] to clear all assignees.
confirm	boolean	yes	Must be true to edit the issue — this is a live mutation.

fn create_issue_comment(index: number, body: string, confirm: boolean)

Comment on an issue (POST /repos/{owner}/{repo}/issues/{index}/comments). Confirm-gated (a live mutation).

Argument	Type	Required	Description
index	number	yes	Issue number to comment on.
body	string	yes	Comment body (markdown).
confirm	boolean	yes	Must be true to create the comment — this is a live mutation.

fn create_user(username: string, email: string, password: string, must_change_password: boolean, restricted: boolean, visibility: enum, confirm: boolean)

Create a normal user account (POST /admin/users). Requires the model's token to have SITE-ADMIN privileges; the created account is a normal (non-admin) user. Defaults to least privilege: must_change_password=true, restricted=false, visibility=private. Confirm-gated (a live mutation).

Argument	Type	Required	Description
username	string	yes	Login for the new account.
email	string	yes	Email address for the new account.
password	string	yes	Initial password for the new account. Sensitive — never logged.
must_change_password	boolean	yes	Force a password change on first sign-in (default true).
restricted	boolean	yes	Create the account as restricted (default false).
visibility	enum	yes	Account visibility (default private — least privilege).
confirm	boolean	yes	Must be true to create the user — this is a live mutation.

fn list_labels()

List labels defined on a repository (GET /repos/{owner}/{repo}/labels). Verify-first before create_label. Excludes org-level labels (GET /orgs/{org}/labels), which org repos may also carry.

fn create_label(name: string, color: string, description: string, exclusive: boolean, is_archived: boolean, confirm: boolean)

Create a label on a repository (POST /repos/{owner}/{repo}/labels). Confirm-gated (a live mutation). A BARE create: it does NOT check for an existing same-named label — verify-first with list_labels. Gitea/Forgejo does NOT enforce unique label names, and list_labels returns only one page by default, so page through before deciding a name is absent or a duplicate may be created.

Argument	Type	Required	Description
name	string	yes	Label name.
color	string	yes	Label color as a 6-digit hex (leading # optional; normalized).
description	string	yes	Label description.
exclusive	boolean	yes	Whether the label is exclusive within its scoped group (default false).
is_archived	boolean	yes	Whether the label is archived (default false).
confirm	boolean	yes	Must be true to create the label — this is a live mutation.

fn list_milestones(state: enum)

List milestones on a repository (GET /repos/{owner}/{repo}/milestones). Verify-first before create_milestone. Only one page is returned by default.

Argument	Type	Required	Description
state	enum	yes	Filter by milestone state.

fn create_milestone(title: string, description: string, due_on?: string, state: enum, confirm: boolean)

Create a milestone on a repository (POST /repos/{owner}/{repo}/milestones). Confirm-gated (a live mutation). A BARE create: it does NOT check for an existing same-titled milestone — verify-first with list_milestones (titles are not unique; only one page is returned by default).

Argument	Type	Required	Description
title	string	yes	Milestone title.
description	string	yes	Milestone description.
due_on?	string	no	Due date as an ISO-8601 datetime (e.g. 2026-12-31T00:00:00Z). Omit for no deadline.
state	enum	yes	Initial milestone state (default open).
confirm	boolean	yes	Must be true to create the milestone — this is a live mutation.

fn add_issue_labels(index: number, labels: array, confirm: boolean)

Add labels to an existing issue (POST /repos/{owner}/{repo}/issues/{index}/labels). Appends to the issue's existing labels. Label IDs are resolved by the caller from a list_labels snapshot. Confirm-gated (a live mutation).

Argument	Type	Required	Description
index	number	yes	Issue number to add labels to.
labels	array	yes	Label IDs to add (resolve from a list_labels snapshot). Appended to the issue's existing labels.
confirm	boolean	yes	Must be true to add the labels — this is a live mutation.

fn create_pull(head: string, base: string, title: string, body: string, labels?: array, milestone?: number, assignees?: array, confirm: boolean)

Open a pull request (POST /repos/{owner}/{repo}/pulls). Confirm-gated (a live mutation). A BARE create — verify-first with list_pulls (state=open) for an existing head->base PR before calling; Forgejo also rejects a duplicate open head->base PR server-side (409/422), so this is not idempotent on its own. `base` is required; resolve label/milestone IDs from list_labels/list_milestones snapshots. Reviewers are set via a separate endpoint and are not supported here.

Argument	Type	Required	Description
head	string	yes	Source branch, or '<user>:<branch>' for a fork's branch.
base	string	yes	Target branch to merge into. Required — read the repo's default branch from a get_repo/list_repos snapshot if you want it.
title	string	yes	Pull request title.
body	string	yes	Pull request body (markdown).
labels?	array	no	Label IDs to apply (resolve from a list_labels snapshot). Omit to apply none.
milestone?	number	no	Milestone ID to associate (resolve from a list_milestones snapshot). Omit for none.
assignees?	array	no	Usernames to assign. Omit to assign none.
confirm	boolean	yes	Must be true to create the pull request — this is a live mutation.

Resources

repos(1h)— Repositories accessible to the authenticated user

repo(1h)— Details for a single repository

issues(30m)— Issues for a repository

issue(30m)— A single issue

pulls(30m)— Pull requests for a repository

pull(30m)— A single pull request

releases(1h)— Releases for a repository

deploy_keys(1h)— Deploy keys registered on a repository

deploy_key(1h)— A single deploy key created on a repository

orgs(1h)— Organizations the authenticated user belongs to

org_repos(1h)— Repositories owned by an organization

org_teams(1h)— Teams within an organization

collaborators(1h)— Collaborators on a repository

user(1h)— A single user account

collaborator(1h)— A synthesized collaborator membership record (the add endpoint returns no body)

team_member(1h)— A synthesized team membership record (the add endpoint returns no body)

issue_comment(30m)— A single comment created on an issue

labels(1h)— Labels defined on a repository

label(1h)— A single label created on a repository

milestones(1h)— Milestones defined on a repository

milestone(1h)— A single milestone created on a repository

issue_labels(30m)— The label set on an issue after an add-labels write

03Previous Versions4

2026.09.29.1Sep 29, 2026

2026.09.28.1Sep 29, 2026

Modified 1 behaviors

2026.07.17.1Jul 18, 2026

Added 1, removed 1 behaviors

2026.04.13.1Apr 14, 2026

04Stats

80 / 100

Downloads

Archive size

33.4 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
License1/2partial
no SPDX license declared
Verified public repository0/2missing

Repository

https://github.com/acme/swamp-forgejo

05Platforms

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

06Labels

#forgejo #gitea #git