n8n-nodes-forgejo-api

n8n nodes for a self-hosted Forgejo instance, built on the official
n8n-nodes-starter. Tested against Forgejo 16.0.3 and
n8n 2.42.5.

• Forgejo covers the whole Forgejo REST API: 496 operations across 32 resources, plus a
  Custom API Call resource for anything else.
• Forgejo Trigger starts a workflow on Forgejo webhook events for a repository, an organization
  or the token owner's repositories. It registers the webhook when the workflow is activated, deletes
  it when the workflow is deactivated, and rejects deliveries whose signature doesn't match.

Operations

Most operations are generated from Forgejo's API description, so their fields match the API:
required fields appear on the node, optional ones under Additional Fields (request body) or
Query Parameters. List operations have Return All and Limit. Operations that return files
(raw file, archive, Actions logs) put them in a binary field, and attachment uploads read one.

A few operations are written by hand for easier use: Repository Get and Get Many (with
filters for archived, mirrored, writable and has-releases), Issue and Pull Request Create,
Get, Get Many, Update and Merge, Issue Comment Create, Get Many, Update
and Delete, and Release Get, Get Many, Delete (keeps the tag) and Get Stale.

File contents (Create, Update) must be Base64-encoded, as the API requires. Use
{{ $json.text.base64Encode() }} in an expression.

Get Stale rules. A release is stale when it is older than Older Than, measured from
published_at. The newest Keep Latest full releases (not draft, not pre-release) are always kept.
A repository with only drafts or pre-releases keeps its newest Keep Latest of those, so a cleanup
never empties a repository's release list.

Credentials

Create a token in Forgejo under Settings > Applications with these scopes:

• read:user
• write:repository (repositories, releases, pull requests, repository webhooks)
• write:issue (issues and comments)

Other resources need their own scope: write:organization for organizations, teams and their
webhooks, write:user for the Current User resource and user webhooks, write:notification,
write:package, write:activitypub, and write:admin (with an admin account) for Admin. Read
scopes are enough for read-only use. A token with every scope is simplest if the workflow does
many things.

In n8n, add a Forgejo API credential with your instance URL (for example
https://git.example.com, no /api/v1) and the token.

Forgejo Trigger

Pick a scope (repository, organization, or user), then the events. When the workflow is activated,
the node creates a Forgejo webhook pointing at n8n with a random secret, and checks each delivery's
X-Forgejo-Signature. Each item has event, eventType, delivery, body (the Forgejo payload)
and headers.

Forgejo must be able to reach n8n's webhook URL. Forgejo refuses to call private addresses by
default, so if both run on a private network, add n8n's host to ALLOWED_HOST_LIST in the
[webhook] section of Forgejo's app.ini, for example ALLOWED_HOST_LIST = n8n.internal.

Install

From n8n: Settings > Community Nodes > Install, then enter n8n-nodes-forgejo-api.

Without npm, build a package file:

npm install
npm run build
npm pack            # writes n8n-nodes-forgejo-api-0.1.0.tgz

Install it into n8n's community nodes folder, then restart n8n:

cd ~/.n8n/nodes
npm install --legacy-peer-deps /path/to/n8n-nodes-forgejo-api-0.1.0.tgz

With Docker, run the same inside the container as the node user, with ~/.n8n on a volume so the
install survives restarts:

docker cp n8n-nodes-forgejo-api-0.1.0.tgz n8n:/tmp/
docker exec -u node n8n sh -c 'cd ~/.n8n/nodes && npm install --legacy-peer-deps /tmp/n8n-nodes-forgejo-api-0.1.0.tgz'
docker restart n8n

~/.n8n/custom also works, but n8n then names the node CUSTOM.forgejo instead of
n8n-nodes-forgejo-api.forgejo, so the bundled workflow would need its node types changed.

Workflow: delete stale releases

workflows/delete-stale-releases.json lists every writable, non-archived, non-mirror repository,
finds stale releases in each, and deletes them. Import it inactive, pick your Forgejo credential on
the three Forgejo nodes, and change the rules in the Settings node:

With dryRun on, the releases appear on the Would delete (dry run) node. Set it to false only
once that list looks right. A deleted release cannot be restored; its git tag stays.

Development

npm run lint
npm test            # builds, then runs the unit tests

The generated operations live in nodes/Forgejo/generated/operations.json. To update them for a
newer Forgejo, download https://<your-forgejo>/swagger.v1.json and run:

node scripts/generate-operations.mjs path/to/swagger.v1.json

Publishing

From a git repository with a remote, npm run release bumps the version, tags, pushes and
publishes. Without one, publish directly (the RELEASE_MODE variable lets past the starter's guard
that otherwise points you to npm run release):

npm login
npm run lint && npm test
RELEASE_MODE=1 npm publish