--- title: "Forgejo and Codeberg" description: "Use Codeberg and self-hosted Forgejo instances: issues, pull requests, notifications, releases and webhooks." canonical_url: "https://forges.link/providers/forgejo" --- # Forgejo and Codeberg > Use Codeberg and self-hosted Forgejo instances: issues, pull requests, notifications, releases and webhooks. The Forgejo provider works with Codeberg and self-hosted Forgejo instances. It can read and write issues and pull requests, and it also covers notifications, commit statuses, releases, repository contents and the webhooks of repositories and organisations. The [Gitea](https://forges.link/providers/gitea) provider uses the same implementation.

Detail	Value
Import	`forges/forgejo`
Factories	`forgejo()` , `forgejoLite()`
Auth	`token` , `anonymous`

## Authentication The provider accepts an access token. If you use an OAuth2 application on Forgejo, the user tokens that it issues work too, and you pass them in the same way: ```ts import { forgejo } from 'forges/forgejo' const forge = forgejo({ auth: { type: 'token', token: process.env.CODEBERG_TOKEN! }, }).create() ``` If you leave out `auth`, the provider makes anonymous reads of public data. ## Instance The default instance is `https://codeberg.org`. To use a self-hosted instance, set `baseUrl` to the root of the instance. The provider appends `/api/v1` itself: ```ts forgejo({ baseUrl: 'https://git.example.com', auth }) ``` `refreshCapabilities()` reads the version of the instance from `/version`. ## Marking notifications done Forgejo notifications have a read state but no done state. To give you `markDone()` anyway, the provider emulates it, which is why it is `'emulated'` in the capabilities. It marks the notification as read, so it leaves the unread listing, and you stay subscribed to the thread. A later change to the thread brings the notification back as unread. To stop those notifications as well, call `unsubscribe()`. ## Merging If you call `merge()` without a `method`, the provider reads the merge styles that the repository allows. When exactly one style is allowed, it uses that one. When several are allowed, it throws `MergeMethodRequiredError`. If you pass `whenChecksPass`, Forgejo merges the pull request after its checks succeed. The merge response has no body, so `merge()` resolves without a `sha`. Its `status` is `'queued'` when Forgejo schedules the merge until the checks pass, and `'merged'` otherwise. Read the pull request to see the merge commit. The head branch stays after `merge()`, even when `deleteBranchOnMerge` is `true`, because Forgejo applies that setting only in its web interface. Gitea did the same before 1.25. ## Reviews Forgejo supports reviews natively. `createReview()` without an `event` creates a pending review, and `submitReview()` submits it. The API doesn't expose whether a review conversation is resolved, so `resolveReviewThread()` isn't available. The API has no endpoint to reply to a review comment either, so `replyToReviewComment()` isn't available. ## Checks and CI `checks.list()` reads commit statuses, and `checks.report()` writes them. `checks.rerun()` isn't available. The `ci` methods read Forgejo Actions. Runs need Forgejo 12 or later, and jobs and job logs need Forgejo 16. Codeberg runs a current release, so they work there out of the box. For a self-hosted instance, pass `instanceVersion` or call `refreshCapabilities()` first. Forgejo before 15 ignores the branch filter, so `ci.runs()` drops the runs of other branches itself, and a page can come back shorter than `perPage`. Forgejo doesn't page the jobs of a run, so `ci.jobs()` returns all of them in one page. ## Changed files `threads.files()` and `contents.compare()` return line counts for each file, but they don't return a `patch`. Forgejo serves diffs only for a whole pull request. With `files: false`, `contents.compare()` asks Forgejo to leave out the changed files of each commit. Forgejo always sends every commit of a comparison, so the provider keeps the newest `commitLimit` of them itself. ## Committing files Forgejo can't check the head of a branch as it commits, so with `expectedHead`, `contents.commitFiles()` reads the branch first and rejects with `BranchMovedError` when it has moved. A commit that lands between the two requests isn't caught. With `createFrom`, the provider creates the branch before the commit. If the commit fails, the provider deletes the branch again, unless it has moved since. Forgejo records `author` as the committer too. Forgejo refuses to write over a symlink, so a change with contents for one rejects with a `422` `ForgeApiError`. Deleting a symlink works. ## Templates Issue templates come from Forgejo's API, which parses `title`, `about`, `labels` and the `fields` of a form. The provider reads each file once more for `body`, with its front matter or the YAML of the form. Pull request templates come from the files themselves. The provider picks the one file the web UI would fill a new pull request with: `PULL_REQUEST_TEMPLATE` or `pull_request_template`, as `.md`, `.yaml` or `.yml`, in the root, `.forgejo/`, `.gitea/`, `.github/` or `docs/`, in that order. Gitea looks only in the root, `.gitea/` and `.github/`. The provider takes the first file that exists without validating it, while the web UI skips a template it can't parse and tries the next. ## Listing an owner's repositories `repos.byOwner()` reads the repositories of a user or an organisation from the same listing, oldest first. Forgejo can't filter or sort that listing, so the provider filters by `visibility` itself, and if you ask for any other order, you get a `sort_unsupported` warning. ## Activity feeds Forgejo serves activity feeds from version 1.20. `users.events()` lists only what the account did, not what others did in its repositories. Forgejo sends no `etag` with a feed, so polling one always reads the whole page. A release in a feed has its title but not its ID, so its event has `kind: 'release'` and no `detail`. ## Search `search.threads()` searches across repositories. It has no `involves` filter, and it returns the results newest first, whatever `sort` or `direction` you pass. If you pass `involves`, you get a `filter_unsupported` warning, and if you pass a `sort` other than `relevance`, you get a `sort_unsupported` warning. ## Webhooks To verify deliveries, set `webhookSecret` to the secret that you configured on the hook: ```ts const forge = forgejo({ webhookSecret: process.env.FORGEJO_WEBHOOK_SECRET, }).create() const events = await forge.webhooks.ingest({ headers: request.headers, body: await request.text(), }) ``` With each delivery, Forgejo sends these headers:

Header	Content
`X-Forgejo-Signature`	The hex HMAC-SHA256 of the body
`X-Forgejo-Event`	The event name
`X-Forgejo-Delivery`	The delivery ID

The provider also accepts the `X-Gitea-*` version of each header. A label delivery doesn't say which labels were added or removed. When the set of labels changes, the provider reports a `label` event with the `edited` action, and when every label is removed, a `label` event with the `unlabelled` action. `webhooks.deliveries()` and `webhooks.redeliver()` aren't available. ## Organisation teams `orgs.teams()` reads `GET /orgs/{org}/teams`, and `orgs.teamMembers()` reads the members of one team. Forgejo addresses a team's members by id, so the provider reads `GET /teams/{id}/members` with the ref's `id`. For a ref with only a `slug`, it first resolves the slug (a team's name) to its id with the teams listing. Both need a token with the `read:organization` scope, and Forgejo responds with a 403 when the account isn't a member of the organisation. A slug that names no team rejects with `NotFoundError`. ## Capabilities

Capability	Support	Without credentials
`experimental`	❌	❌
`sources.poll`	✅	❌
`sources.webhook`	✅	✅
`sources.subscribe`	❌	❌
`repos.get`	✅	✅
`users.get`	✅	✅
`users.me`	✅	❌
`users.sponsorable`	❌	❌
`users.events`	✅	✅
`repos.list`	✅	❌
`repos.byOwner`	✅	✅
`repos.labels`	✅	✅
`repos.createLabel`	✅	❌
`repos.milestones`	✅	✅
`repos.collaborators`	✅	❌
`repos.contributors`	❌	❌
`repos.contributorStats`	❌	❌
`repos.templates`	✅	✅
`repos.permissionFor`	✅	❌
`repos.addCollaborator`	✅	❌
`repos.assignableUsers`	✅	❌
`repos.reviewerCandidates`	✅	❌
`repos.events`	✅	✅
`orgs.teams`	✅	❌
`orgs.teamMembers`	✅	❌
`threads.get`	issue, PR, commit	issue, PR, commit
`threads.list`	issue, PR	issue, PR
`threads.getMany`	✅	✅
`threads.events`	issue, PR, commit	issue, PR, commit
`comments.list`	issue, PR	issue, PR
`comments.get`	issue, PR	issue, PR
`comments.edit`	issue, PR	❌
`comments.delete`	issue, PR	❌
`reactions.list`	issue, PR	issue, PR
`notifications.list`	✅	❌
`notifications.markRead`	✅	❌
`notifications.markDone`	emulated	❌
`notifications.unsubscribe`	✅	❌
`notifications.markAllRead`	✅	❌
`notifications.markAllDone`	❌	❌
`notifications.unreadCount`	✅	❌
`writes.comment`	issue, PR	❌
`writes.upsertComment`	issue (emulated), PR (emulated)	❌
`writes.close`	issue, PR	❌
`writes.reopen`	issue, PR	❌
`writes.create`	issue, PR	❌
`writes.update`	issue, PR	❌
`writes.setLabels`	issue, PR	❌
`writes.addLabels`	issue, PR	❌
`writes.removeLabels`	issue, PR	❌
`writes.setMilestone`	issue, PR	❌
`writes.react`	issue, PR	❌
`writes.setAssignees`	issue, PR	❌
`writes.requestReview`	PR	❌
`writes.merge`	✅	❌
`writes.approveAndMerge`	✅	❌
`writes.transfer`	❌	❌
`writes.markDuplicate`	❌	❌
`subscriptions.get`	issue, PR	❌
`subscriptions.set`	issue, PR	❌
`installations`	❌	❌
`checks.thread`	PR	PR
`checks.list`	✅	✅
`checks.get`	❌	❌
`checks.report`	✅	❌
`checks.rerun`	❌	❌
`ci.runs`	✅	✅
`ci.run`	✅	✅
`ci.jobs`	✅	✅
`ci.job`	emulated	emulated
`ci.log`	✅	✅
`contents.file`	✅	✅
`contents.tree`	✅	✅
`contents.branches`	✅	✅
`contents.tags`	✅	✅
`contents.resolveRef`	✅	✅
`contents.commits`	✅	✅
`contents.commit`	✅	✅
`contents.compare`	✅	✅
`contents.commitFiles`	✅	❌
`contents.threadFiles`	✅	✅
`contents.threadCommits`	✅	✅
`reviews.list`	✅	✅
`reviews.get`	✅	✅
`reviews.create`	✅	❌
`reviews.submit`	✅	❌
`reviews.approve`	✅	❌
`reviews.reply`	❌	❌
`reviews.resolveThread`	❌	❌
`releases.list`	✅	✅
`releases.get`	✅	✅
`releases.latest`	✅	✅
`releases.getByTag`	✅	✅
`releases.downloadAsset`	✅	✅
`releases.create`	✅	❌
`releases.update`	✅	❌
`webhooks.list`	✅	❌
`webhooks.create`	✅	❌
`webhooks.update`	✅	❌
`webhooks.delete`	✅	❌
`webhooks.rotateSecret`	✅	❌
`webhooks.deliveries`	❌	❌
`webhooks.redeliver`	❌	❌
`search.threads`	✅	✅
`search.repos`	✅	✅
`search.commits`	❌	❌
`search.code`	❌	❌
`securityAlerts`	❌	❌
`eventKinds`	native	native
`authKinds`	`token` , `anonymous`	`token` , `anonymous`
`limits`	unknown	unknown

## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.