Platforms

Gitee

Gitee repositories, issues and pull requests in the same shapes as every other forge. Issues keep their text keys.
IDgitee05 / 08gitee.com/api/v5
Platform / gitee

Gitee

Spoken by GiteeProvider. Same resources, same shapes, its own quirks kept inside.

Access

CreatecreateProvider("gitee")

Importimport { GiteeProvider } from"@agntn/forges/gitee"

EnvGITEE_TOKEN, GITEE_ACCESS_TOKEN

CLInone, there's no Gitee CLI login

Header
Authorization: token
Anonymous
public repositories, until a plain-text 403 a few dozen requests in
Threads
unsupported, explicit error
Code search
unsupported, explicit error
Templates
none

Read a Gitee repository

ts
import { createProvider } from "@agntn/forges";

const gitee = await createProvider("gitee", { token: process.env.GITEE_TOKEN });

const docs = { owner: "openharmony", repo: "docs" };
const issue = await gitee.issues.get({ ...docs, number: "ICK440" });
const pull = await gitee.pullRequests.get({ ...docs, number: 95569 });
const readme = await gitee.repos.readContents(docs, { path: "README.md" });

Spot the odd one out? The issue goes by "ICK440", a string. Gitee numbers its pull requests like everyone else, but an issue gets a key of letters and digits.

So Issue.number is number | string. On every other forge it stays a number. A pull request is a number on Gitee too, and a key there is a 400 before any request.

The default API base is https://gitee.com/api/v5. forges adds /api/v5 when it's missing. The enterprise edition at e.gitee.com is a different API, and it's out.

Where does the token come from?

@agntn/credentials/gitee checks an explicit token first. Then GITEE_TOKEN, then GITEE_ACCESS_TOKEN. That's the whole chain. No Gitee CLI keeps a login to read.

Pass { token: "" } for anonymous reads. They work, for a while. Gitee counts anonymous calls per address, and a few dozen in its firewall answers a plain-text 403. forges reads that as a rate limit, not a permission problem. A token is the sane choice.

What it reads

Endpoints are relative to /api/v5. In the table, … means /repos/:owner/:repo.

ResourceEndpoint
Repositories and tagsGET …, GET /orgs/:org/repos or GET /users/:user/repos, GET …/tags
IssuesGET …/issues, GET …/issues/:key, GET …/issues/:key/comments
Pull requestsGET …/pulls, GET …/pulls/:number, with /files, /comments and /commits
Timelinesthe comments plus operate_logs, merged by time
Commits, releases and usersGET …/commits, GET …/commits/:sha, GET …/releases, GET /users/:login
Repository contentsthe ref resolved through GET …/commits/:ref, then GET …/contents/:path?ref=
Commit comparisonGET …/compare/:base...:head

What comes back

  • Issue.number is the key, "ICK440". Pass it back as is. PullRequest.number is a number.
  • An issue's state is open while Gitee says open or progressing, and closed for closed or rejected.
  • Gitee keeps one assignee per issue, so assignees has one entry at most.
  • cloneUrl ends in a single .git. Gitee's html_url already carries one, and forges doesn't add a second.
  • A file read pins the ref to its resolved commit. A continuation past offset zero must pass that SHA.
  • Directory entries carry size for files and null for directories.
  • A comparison lists at most 100 commits. Past that Gitee sets truncated, and forges answers filesComplete: null, because the list is a floor, not the range.

Gotchas

Why would a missing file come back as an empty folder?

  • Gitee answers 200 with [] for a path that isn't there. forges turns an empty listing outside the root into a 404. A real empty directory can't exist in Git anyway.
  • GET /orgs/:org/repos answers 500 for some big organizations, openharmony and mindspore among them. That's Gitee's error, and it comes back as one. Read a known repository with repos.get instead.
  • Gitee's anonymous limit hits fast. One explorer session can spend it.

What isn't there

Each operation below returns a ForgesError with status 501 and a sentence. An agent can stop instead of retrying.

Gitee has no CI runs in its API, so ciRuns.* is a 501. Review threads, reactions, code search and templates are 501 too, and so are issue fields and sub issues.

Some gaps are ours, not Gitee's. Creating an issue or a pull request works, and so do comment edits and deletes. Posting a new comment, editing an issue or pull request, merging, reviews, patches and issue search aren't wired up yet. Same 501, same sentence.

Where it lives

The provider lives in src/providers/gitee.ts. It uses the forges/gitee adapter and gets tokens from @agntn/credentials/gitee.