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
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.
| Resource | Endpoint |
|---|---|
| Repositories and tags | GET …, GET /orgs/:org/repos or GET /users/:user/repos, GET …/tags |
| Issues | GET …/issues, GET …/issues/:key, GET …/issues/:key/comments |
| Pull requests | GET …/pulls, GET …/pulls/:number, with /files, /comments and /commits |
| Timelines | the comments plus operate_logs, merged by time |
| Commits, releases and users | GET …/commits, GET …/commits/:sha, GET …/releases, GET /users/:login |
| Repository contents | the ref resolved through GET …/commits/:ref, then GET …/contents/:path?ref= |
| Commit comparison | GET …/compare/:base...:head |
What comes back
Issue.numberis the key,"ICK440". Pass it back as is.PullRequest.numberis a number.- An issue's state is
openwhile Gitee saysopenorprogressing, andclosedforclosedorrejected. - Gitee keeps one assignee per issue, so
assigneeshas one entry at most. cloneUrlends in a single.git. Gitee'shtml_urlalready 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
sizefor files andnullfor directories. - A comparison lists at most 100 commits. Past that Gitee sets
truncated, and forges answersfilesComplete: 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/reposanswers 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 withrepos.getinstead.- 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.