--- title: "Gitea" description: "Use gitea.com and self-hosted Gitea instances. It shares its implementation with the Forgejo provider." canonical_url: "https://forges.link/providers/gitea" --- # Gitea > Use gitea.com and self-hosted Gitea instances. It shares its implementation with the Forgejo provider. The Gitea provider works with gitea.com and self-hosted Gitea instances. It shares its implementation with the [Forgejo](https://forges.link/providers/forgejo) provider, so the Forgejo page applies here too, apart from the default instance, the webhook headers and CI. Refs from this provider have `forge: 'gitea'`.

Detail	Value
Import	`forges/gitea`
Factories	`gitea()` , `giteaLite()`
Auth	`token` , `anonymous`

## Authentication The provider accepts an access token: ```ts import { gitea } from 'forges/gitea' const forge = gitea({ auth: { type: 'token', token: process.env.GITEA_TOKEN! }, }).create() ``` If you leave out `auth`, the provider makes anonymous reads of public data. ## Instance The default instance is `https://gitea.com`. To use a self-hosted instance, set `baseUrl` to the root of the instance. The provider appends `/api/v1` itself: ```ts gitea({ baseUrl: 'https://gitea.example.com', auth }) ``` `refreshCapabilities()` reads the version of the instance from `/version`. ## Behaviour shared with Forgejo Because Gitea and Forgejo share an implementation, the following sections of the Forgejo page describe Gitea as well: - [Marking notifications done](https://forges.link/providers/forgejo#marking-notifications-done) - [Merging](https://forges.link/providers/forgejo#merging) - [Reviews](https://forges.link/providers/forgejo#reviews) - [Changed files](https://forges.link/providers/forgejo#changed-files) - [Committing files](https://forges.link/providers/forgejo#committing-files) - [Templates](https://forges.link/providers/forgejo#templates) - [Listing an owner's repositories](https://forges.link/providers/forgejo#listing-an-owners-repositories) - [Activity feeds](https://forges.link/providers/forgejo#activity-feeds) - [Search](https://forges.link/providers/forgejo#search) ## Review replies `replyToReviewComment()` needs Gitea 1.27 or later. It replies by the comment's `ref`, and the reply joins the same review. gitea.com runs a recent build, so it works there out of the box. For a self-hosted instance, pass `instanceVersion` or call `refreshCapabilities()` first. ## Checks and CI `checks.list()` reads commit statuses, and `checks.report()` writes them. The `ci` methods read Gitea Actions. Runs and their jobs need Gitea 1.25 or later, and job logs need Gitea 1.24. gitea.com runs a recent build, so they work there out of the box. For a self-hosted instance, pass `instanceVersion` or call `refreshCapabilities()` first. Gitea 1.25 is stricter about the list of runs: it shows it only to the owners of the repository and to site admins, and responds with `403` to anyone else. From 1.26, everyone who can read the repository can list its runs. Without a token, Gitea responds with `401` to the list of runs and to job logs, so an anonymous provider can read a run and its jobs, but not list runs or read logs. Gitea before 28 doesn't say when a run was created, so `createdAt` is unset there. ## Webhooks To verify deliveries, set `webhookSecret` to the secret that you configured on the hook: ```ts const forge = gitea({ webhookSecret: process.env.GITEA_WEBHOOK_SECRET, }).create() const events = await forge.webhooks.ingest({ headers: request.headers, body: await request.text(), }) ``` With each delivery, Gitea sends these headers:

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

Unlike the Forgejo provider, the Gitea provider doesn't read `X-Forgejo-*` headers. 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. ## Organisation teams `orgs.teams()` reads `GET /orgs/{org}/teams`, and `orgs.teamMembers()` reads the members of one team. Gitea 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 Gitea 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`	✅	unverified
`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.