> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Gitee > Configure the Gitee repository connector and limit indexing to approved repositories, branches, and content types. 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](https://gitee.com/profile/personal_access_tokens/new). * 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](https://gitee.com/profile/personal_access_tokens/new). For permission context, see [Gitee help: create a personal access token with project permission](https://gitee.com/help/articles/4336). | | 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](https://gitee.com/api/v5/swagger) 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 1. Create the connector with a test repository and confirm the credential can read the repository. 2. Search for a README, config file, or representative source snippet to confirm file indexing. 3. Search for a known issue title, body keyword, and comment keyword to confirm issue scope. 4. 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. 5. Search for an unlisted repository, an unselected branch, or a skipped directory to confirm it does not return results. 6. Test with an in-group user and an out-of-group user to verify the AIvis access boundary. 7. 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](https://gitee.com/help/articles/4336) ## Related Pages * [Connectors and Indexing](/aivis/knowledge/connectors) * [Index Settings](/aivis/knowledge/index-settings) * [Users, Groups, and Roles](/aivis/governance/users-and-groups)