---
title: "Gitee"
description: "Gitee repositories, issues and pull requests in the same shapes as every other forge. Issues keep their text keys."
canonical_url: "https://forges.agntn.dev/platforms/gitee"
---
# Gitee

> Gitee repositories, issues and pull requests in the same shapes as every other forge. Issues keep their text keys.

<platform-facts platform="gitee">



</platform-facts>

## 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`.

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      Endpoint
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Repositories and tags
    </td>
    
    <td>
      <code>
        GET …
      </code>
      
      , <code>
        GET /orgs/:org/repos
      </code>
      
       or <code>
        GET /users/:user/repos
      </code>
      
      , <code>
        GET …/tags
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Issues
    </td>
    
    <td>
      <code>
        GET …/issues
      </code>
      
      , <code>
        GET …/issues/:key
      </code>
      
      , <code>
        GET …/issues/:key/comments
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Pull requests
    </td>
    
    <td>
      <code>
        GET …/pulls
      </code>
      
      , <code>
        GET …/pulls/:number
      </code>
      
      , with <code>
        /files
      </code>
      
      , <code>
        /comments
      </code>
      
       and <code>
        /commits
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Timelines
    </td>
    
    <td>
      the comments plus <code>
        operate_logs
      </code>
      
      , merged by time
    </td>
  </tr>
  
  <tr>
    <td>
      Commits, releases and users
    </td>
    
    <td>
      <code>
        GET …/commits
      </code>
      
      , <code>
        GET …/commits/:sha
      </code>
      
      , <code>
        GET …/releases
      </code>
      
      , <code>
        GET /users/:login
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Repository contents
    </td>
    
    <td>
      the ref resolved through <code>
        GET …/commits/:ref
      </code>
      
      , then <code>
        GET …/contents/:path?ref=
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Commit comparison
    </td>
    
    <td>
      <code>
        GET …/compare/:base...:head
      </code>
    </td>
  </tr>
</tbody>
</table>

## 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`.


## Sitemap

See the full [sitemap](https://forges.agntn.dev/sitemap.md) for all pages.
