tea-git

Drop-in replacement for Octokit 5.x targeting Gitea API 1.25+.

Swap your imports, keep the same syntax.

Install

npm install tea-git

Quick Start

// Before (Octokit)
import { Octokit } from "octokit";
const octokit = new Octokit({ auth: "ghp_..." });

// After (tea-git)
import { TeaGit } from "tea-git";
const tea = new TeaGit({
  auth: "your-gitea-token",
  baseUrl: "https://gitea.example.com",
});

// Same syntax — just works
const { data: repo } = await tea.repos.get({ owner: "org", repo: "lib" });
const { data: issues } = await tea.issues.listForRepo({
  owner: "org",
  repo: "lib",
  state: "open",
});

// legacy .rest accessor also works (same instances, zero overhead)
const { data: pr } = await tea.rest.pulls.get({ owner: "org", repo: "lib", pull_number: 1 });

Migration from Octokit

1. Replace octokit / @octokit/rest with tea-git in package.json.
2. Update imports:

   - import { Octokit } from "octokit";
   + import { TeaGit } from "tea-git";

3. Add baseUrl to the constructor (required for self-hosted Gitea):

   - const client = new Octokit({ auth: token });
   + const client = new TeaGit({ auth: token, baseUrl: "https://gitea.example.com" });

4. Replace Octokit type references with TeaGit.

Every namespace (client.repos, client.pulls, etc.) keeps the same method names and parameter shapes.

Namespaces

| Namespace | Accessor | Coverage highlights | | --------- | ----------------- | -------------------------------------------------------- | | repos | tea.repos.* | CRUD, branches, collaborators, contents, forks, releases | | issues | tea.issues.* | CRUD, comments, labels, lock/unlock | | pulls | tea.pulls.* | CRUD, merge, reviews, files, commits, reviewers | | users | tea.users.* | Authenticated user, by username, followers, keys, search | | orgs | tea.orgs.* | CRUD, members, repos | | teams | tea.teams.* | CRUD, members, repos, get-by-name resolution | | git | tea.git.* | Refs, commits, trees, blobs, tags, notes |

API Differences

Pagination

Gitea uses limit instead of per_page. tea-git maps per_page → limit automatically, so existing code works unchanged.

Teams

Gitea identifies teams by numeric ID. teams.getByName({ org, team_slug }) resolves the slug to an ID transparently (one extra API call). For direct access, use teams.getById({ team_id }).

Merge strategies

pulls.merge() accepts a Do field with Gitea-specific values:

await tea.pulls.merge({
  owner: "org",
  repo: "lib",
  pull_number: 42,
  Do: "squash",                    // "merge" | "rebase" | "rebase-merge" | "squash" | "manually-merged"
  delete_branch_after_merge: true,
});

Input Validation

Every method validates inputs with Zod before sending the request. Invalid parameters throw a ZodError immediately, without hitting the network.

Schemas are exported for reuse:

import { IssueCreateParams } from "tea-git/schemas/commons/issues";

Response Shape

Every method returns the same shape as Octokit:

interface TeaGitResponse<T> {
  status: number;
  url: string;
  headers: Record<string, string>;
  data: T;
}

Error Handling

Network and API errors throw TeaGitError:

import { TeaGitError } from "tea-git";

try {
  await tea.repos.get({ owner: "x", repo: "y" });
} catch (err) {
  if (err instanceof TeaGitError) {
    console.error(err.status, err.message);
  }
}

Escape Hatch

For endpoints not yet covered by a namespace, use the low-level request method:

const { data } = await tea.request("GET", "/repos/org/lib/statuses/abc123");

License

MIT