Gitee | Alephant Documentation

The Gitee connector brings approved Gitee repository files, issues, and pull requests into AIvis knowledge retrieval. It is not a Gitee permission-sync connector: the Gitee token controls what AIvis can ingest, and AIvis connector access controls who can search the indexed content.

Use cases

Scenario	Recommendation
Repository Q&A	Create a connector for one project or for a small repository set with the same audience.
README and engineering docs	Enable source files first, and start with the default branch or a stable release branch.
Issue / PR decision history	Enable issues and pull requests so agents can retrieve context, discussions, and resolution records.
Private repositories	Use a dedicated Gitee personal access token and make the connector visible only to private AIvis groups.
Multi-team repositories	Split connectors by owner, project, or audience so one token and one connector do not cover too much.

Indexed Content

The Gitee connector is scoped by one repository owner and one or more repository names. It indexes only the repositories listed in the form. It never auto-discovers every repository visible to the token.

Gitee content	Indexing behavior
Source files	When Include source files is enabled, the connector reads the recursive tree for the target branch and indexes files that can be processed as text. Repository, branch, path, and file type are stored as metadata.
Issues	When Include issues is enabled, the connector reads issues in all states and indexes title, body, comments, state, author, and labels.
Pull requests	When Include pull requests is enabled, the connector reads pull requests in all states and indexes title, body, comments, state, and author. It does not index diffs, commits, pipelines, review state, or code-change details.
Repository hierarchy	Each repository is emitted as a parent folder node so search results can show their source repository.

File indexing has built-in guardrails. Files larger than 1 MB, binary files, *.min.js, *.min.css, and files under .git, .venv, __pycache__, build, dist, node_modules, target, or vendor are skipped. Common text source files, config files, Markdown, YAML, JSON, SQL, README, LICENSE, Dockerfile, and Makefile are eligible.

The connector does not currently index Gitee Wiki pages, releases, milestones, commits, repository statistics, pipelines, or repository settings.

Prerequisites

Confirm that the target repositories are on gitee.com. The current connector uses https://gitee.com/api/v5 and does not support self-hosted Gitee hosts.
Create a dedicated Gitee personal access token for AIvis indexing. You can create it from the Gitee personal access tokens page.
Make sure the token owner can read the target repositories, issues, pull requests, and branch files. For indexing-only use, avoid write, hook, and admin permissions.
Record the repository owner and repository path. For https://gitee.com/openmodels/search, the owner is openmodels and the repository name is search.
Decide the AIvis access boundary before indexing. Anyone who can search this connector can search all content produced by the connector.
Allow the AIvis backend to reach gitee.com.

Gitee help pages commonly describe project permission as the repository API permission for personal tokens. The exact permission UI can vary by Gitee account type or tenant; verify the token against the repository, issue, pull-request, and file APIs you plan to index, and keep permissions minimal.

Where to get configuration values

Configuration value	Where to get it
Gitee personal access token	Sign in to Gitee and create a dedicated token from the personal access tokens page. For permission context, see Gitee help: create a personal access token with project permission.
Repository Owner	Take `{owner}` from `https://gitee.com/{owner}/{repo}`. Enter only the path component, not the full URL.
Repository Name	Take `{repo}` from `https://gitee.com/{owner}/{repo}`. For batch configuration, first confirm the repositories share one owner and audience.
Branch	Confirm it from the repository branch list or default-branch setting. Leave this field empty to use the repository default branch.
File, issue, and pull-request API readability	Use the Gitee API v5 documentation to verify that the token can read target repositories, issues, pull requests, and file contents.

Create a Gitee Token

In Gitee account settings, open Personal access tokens and create a token dedicated to AIvis. Use a clear description such as aivis-gitee-indexer, and select only the repository-read permissions required for indexing.

After creation, copy the token once and save it directly as an AIvis credential. Do not put the real token in docs, screenshots, tickets, chat logs, agent instructions, or code repositories.

Configure AIvis

In the admin panel, open Connectors and choose Gitee. Create or select a Gitee credential, then configure repository scope and content types.

Field	Value	Notes
Gitee Personal Access Token	Paste the dedicated token	Used to call the Gitee API. Saved values are usually not shown in plaintext.
Connector name	Example: `Engineering handbook`	Helps admins identify the connector and logs.
Repository Owner	Example: `openmodels`	Enter only the owner path component, not the full URL.
Gitee Repositories	Example: `search`, `web-ui`	Enter repository names only. Up to 100 repositories; duplicates are rejected.
Branch	Example: `main`, `master`, `release/v1`	Leave empty to use each repository’s default branch.
Include source files	Enabled by default	Reads indexable text files from the target branch.
Include issues	Enabled by default	Reads issue body and comments in all states.
Include pull requests	Enabled by default	Reads PR body and comments in all states, not diffs.

At least one content type must be enabled. Repository owner and repository names must be safe path components: letters, numbers, dots, underscores, and hyphens. Do not paste empty strings, slash-delimited paths, or full URLs into these fields.

Sync Behavior

Connectors created from the standard admin panel use polling and checkpointed continuation. One sync pass processes repositories in order, and each repository processes enabled stages in this order: files, issues, pull requests.

Stage	Details
Files	Resolves the configured branch, or the repository default branch when the branch field is empty. The connector freezes the current commit tree and processes indexable files by path.
Issues	Reads issues in all states by page and emits entries updated within the sync window. Each issue also fetches comments.
Pull requests	Reads pull requests in all states by page and emits entries updated within the sync window. Each PR also fetches comments.
Cleanup	Removed or newly out-of-scope documents depend on connector cleanup / prune settings. To verify deletion, run a full sync and confirm old documents are pruned.

For large repositories, test with one repository and one content type first. The connector enforces a 1 MB blob limit and has guardrails for comments and total inventory size; very large items may be skipped or stop a sync.

Permissions

The Gitee token controls what AIvis can ingest, but this connector does not sync Gitee repository members, enterprise roles, private repository permissions, branch protection, or per-issue permissions into AIvis.

Search access is controlled only by AIvis connector access settings:

AIvis access setting	Meaning
Private groups	Only selected AIvis groups can search all documents produced by this connector. Recommended for private repositories, customer projects, and internal projects.
Public	Any AIvis user with access to this knowledge scope may search the indexed content. Use only when all content is appropriate for that audience.
Permission sync	Gitee does not support this mode. Connector creation is rejected when permission sync is selected.

Do not use a Gitee connector as a shared proxy to bypass Gitee repository permissions. For different teams, customers, projects, or confidentiality levels, use different tokens, connectors, and private AIvis groups.

Verification

Create the connector with a test repository and confirm the credential can read the repository.
Search for a README, config file, or representative source snippet to confirm file indexing.
Search for a known issue title, body keyword, and comment keyword to confirm issue scope.
Search for a known PR title, body keyword, and comment keyword to confirm PR scope, and verify diff-only code does not appear as PR content.
Search for an unlisted repository, an unselected branch, or a skipped directory to confirm it does not return results.
Test with an in-group user and an out-of-group user to verify the AIvis access boundary.
Modify a test file or comment, wait for the next sync, and confirm the update is searchable.

Troubleshooting

Symptom	Checks
Authentication failure or Gitee API request failure	Confirm the token is complete, unexpired, not revoked, and that the backend can reach `gitee.com`.
Repository validation fails	Check that owner and repository fields contain path components only, and that the token account can open the repository.
Self-hosted Gitee cannot be configured	The current connector is fixed to `https://gitee.com/api/v5` and does not support custom Gitee hosts.
Only some repositories are indexed	Confirm the repository list is complete, has no duplicates, and does not exceed the 100-repository limit.
Files are missing	Check Include source files, branch value, file size, skipped directories, binary content, and minified file names.
Issues or PRs are missing	Check the corresponding content switch, token access to the issue / PR APIs, and whether the item was updated within the sync window.
Users can search content they cannot open in Gitee	This is an AIvis access-scope issue. Move the connector to private groups or split connectors by audience.
Token leaked	Revoke or regenerate the token in Gitee immediately, update the AIvis credential, and rerun verification.

Security and Maintenance

Use separate tokens per environment, such as production, staging, and demos.
Use separate connectors for sensitive projects so access, audits, and disablement stay precise.
Periodically review repository list, branch, content switches, access groups, and token owner.
When a repository owner or name changes, update the connector and run a full verification pass.
When the connector is no longer needed, disable it in AIvis first, then revoke the Gitee token.

Official References

Gitee help: create a personal access token with project permission