Gitea authentication

Authenticate the Gitea provider on gitea.com, a self-hosted instance, or Forgejo.

The gitea provider from repo-sdk/gitea authenticates with a personal access token and targets self-hosted instances — including Forgejo — via a baseUrl that includes /api/v1.

Token auth

Create a personal access token under Settings → Applications → Manage Access Tokens. The SDK sends it with Gitea’s token authorization scheme (the literal word token, not Bearer).

import { createClient } from 'repo-sdk';
import { gitea } from 'repo-sdk/gitea';

const client = createClient({
  provider: gitea({ auth: { token: process.env.GITEA_TOKEN! } }),
});

Scopes

Pick the token scope for what you’ll do:

• read:repository — required for discovery, commits, tags, archive downloads, and clone access.
• write:repository — additionally required to create, update, or delete webhooks.
• read:organization — required to list organization namespaces.

Self-hosted instances and Forgejo

For a self-hosted Gitea, pass the full API base URL including the /api/v1 suffix — it is used verbatim. The default is https://gitea.com/api/v1.

gitea({
  auth: { token: process.env.GITEA_TOKEN! },
  baseUrl: 'https://gitea.example.com/api/v1',
});

Forgejo exposes the same /api/v1 API, accepts the same token scheme, and sends the same X-Gitea-* webhook headers — the provider works against Forgejo unchanged.

Expiring tokens

auth: { tokenProvider } mints the bearer token per request, with one forced-refresh retry on 401 — see Expiring tokens for the contract.