> 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. # GitHub > 配置 GitHub 仓库索引，并明确仓库、内容、主机、增量同步与权限边界。 ## 索引内容 GitHub 连接器会索引一个 GitHub 用户或组织名下仓库中的内容。可以填写逗号分隔的仓库列表，也可以选择**全部**按 owner 列举。Owner 为组织时，**全部**可以列举 token 可见的组织仓库。Owner 为用户时，它调用 `/users/{user}/repos`，只列举公开仓库；用户 owner 下的私有仓库必须明确填写 repository name。 | GitHub 数据 | 索引行为 | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Pull request | 每个 PR 会成为一个文档，可搜索文本是 PR 正文。文档标识由 PR 编号与标题组成；状态、标签、作者、经办人、合并状态，以及若干时间戳和计数会成为元数据。Review、评论、diff 与 commit 内容不会加入文本。 | | Issue | 每个非 PR issue 会成为一个文档，可搜索文本是 issue 正文。标题与编号用于标识文档，状态、标签、作者、经办人与时间戳会成为元数据。Issue 评论不会被索引。 | | 仓库文档 | 选择**包含文档**时，OpenCore 只读取仓库默认分支。它接受 `.md`、`.mdx`、`.markdown`、`.rst`、`.txt`，以及 `README`、`LICENSE`、`CHANGELOG`、`CODEOWNERS` 等常见无扩展名文件。源码与数据/配置类扩展名会被有意排除。 | | 文件限制 | 超过 1,000,000 字节的文件，以及位于内置依赖/构建路径分段下的文件会被跳过。GitHub 截断超大型递归树时，OpenCore 会索引已返回的路径，并报告树不完整失败。 | | 分支 | 没有分支字段。文档文件只来自当前默认分支；PR 与 issue 属于整个仓库，不按分支筛选。 | 必须至少选择 pull request、issue 或文档中的一项。连接器不会为仓库概览单独创建可搜索文档。 ## 前置条件 * 创建专用 GitHub access token，使其能读取每个选定仓库及已启用的 PR、issue 与 contents API。 * 当前连接器凭据只有一个 access-token 字段，不包含 GitHub App ID、installation ID、client secret 或 private-key 字段；不要把 App private key 粘贴到 token 字段。 * 对于受 SAML SSO 保护的组织仓库，应为该组织授权 token。 * 记录准确的仓库 owner；使用明确范围时，还应记录每个不带 owner 前缀的仓库名。如果 owner 是用户，请记录每个所需私有仓库并明确填写，因为**全部**不会列举这些仓库。 * 对于 GitHub Enterprise，由部署运维人员把部署级 `GITHUB_CONNECTOR_BASE_URL` 设置为实例 API base URL。未设置时，客户端使用 GitHub.com。管理表单不能为单个连接器设置主机。 * 允许 OpenCore worker 访问所选 GitHub API 主机，并允许用户浏览器访问对应 Web 主机上的结果链接。 * 如果使用**自动同步权限**，token 还必须能够读取仓库可见性、collaborator、outside collaborator、team、组织成员，以及把 GitHub 身份匹配到 OpenCore 用户所需的邮箱值。 ## 凭据 | 方式 | OpenCore 凭据值 | 认证行为 | | ------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | | GitHub access token | `github_access_token: ` | OpenCore 会把 token 传给 GitHub API 客户端。验证、内容读取，以及启用自动同步时的权限读取会使用同一个 token。 | GitHub.com 与 GitHub Enterprise 由部署配置选择，不由凭据值选择。当前连接器 schema 没有独立的 GitHub App 凭据流程。不同 token 类型与服务器使用的 scope 名称可能不同；应验证实际目标仓库，并在适用时验证权限端点，而不能只依赖名义上的 scope 标签。 ## 在 OpenCore 中配置 1. 在管理后台打开**连接器**，选择 **GitHub**，并创建 access-token 凭据。 2. 在**仓库 Owner** 中填写一个准确的 GitHub 用户或组织。 3. 选择**指定仓库**并填写一个或多个逗号分隔的仓库名，或选择**全部**按 owner 列举。Owner 为组织时，它会请求 token 可见的组织仓库。Owner 为用户时，它使用 `/users/{user}/repos` 且只返回公开仓库；用户私有仓库应在**指定仓库**中填写。**全部**并非账号级全范围：配置的 owner 仍然是边界。 4. 至少选择一种内容：pull request、issue 或文档。仅当默认分支文档文件策略符合预期内容时才选择文档。 5. 选择文档访问方式。仅在**自动同步权限**可用且仓库级映射已完成测试时使用它。否则，受限仓库应使用 OpenCore **私有**群组；仅当每个 OpenCore 账号都可以搜索全部选定内容时才使用**公开**。 6. 设置刷新与清理选项，创建连接器并启动索引。 首次 checkpoint 调用会解析已配置仓库，保存其 ID 与首个仓库，然后在不产生内容的情况下返回。后续调用会逐个仓库推进 PR、issue 与文件分页。 增量运行时，PR 与 issue 按更新时间排序。OpenCore 会先把轮询起点向前移动三小时、终点向后移动一天，再进行筛选。对于文件，会把调整后的起点与仓库 `pushed_at` 比较；仓库足够新时会重新列举当前默认分支文档集。因此，向任何分支推送都可能触发默认分支文档的重新处理。 ## 权限 Access token 决定 OpenCore 可以摄取什么。**自动同步权限**可用且已选择时，当前 Enterprise 实现会把一条仓库级访问记录应用到该仓库内的每个 PR、issue 与文件文档： * 公开仓库映射为 OpenCore 公开访问。 * 私有仓库映射为仓库 collaborator、outside collaborator 与仓库 team 对应的群组。 * Internal 仓库映射为组织成员群组。 这是仓库级同步，不是分支、issue 或 PR 级授权，也不会复现粒度更细的源规则。群组成员根据 GitHub 邮箱值构建；如果 collaborator、team 成员或组织成员没有可用邮箱，他们可能不会出现在同步后的 OpenCore 群组中。依赖自动同步前，应同时测试允许与拒绝用户。 未使用自动同步时，用户搜索时不会检查 GitHub 访问权限。**私有**使用分配给连接器的 OpenCore 群组；**公开**会让每个 OpenCore 账号都能搜索全部已索引文档。如果 OpenCore 访问模式比源端更宽，用户可能可以搜索自己无法在 GitHub 打开的 PR、issue 或文件。 ## 验证 1. 验证连接器并检查实际解析出的仓库列表。组织使用**全部**时，确认每个预期的 token 可见组织仓库都存在。用户使用**全部**时，应预期只返回公开仓库，并确认每个所需私有仓库均已明确配置。 2. 持续执行 checkpoint 调用直到运行完成，然后针对每个已启用内容类型，搜索一个选定 PR 正文、一个 issue 正文，以及一个默认分支 README 或文档文件。 3. 确认 PR 评论、review、diff、issue 评论、源码文件、超大文档，以及只存在于非默认分支的文档均不存在。 4. 打开结果链接，确认它们指向预期 GitHub.com 或 GitHub Enterprise 主机；对于文件，还应确认链接使用当前默认分支。 5. 对 PR 或 issue 做一次增量修改，确认它能在连接器三小时起点重叠范围内出现。推送一个选定文档，并确认默认分支文件已更新。 6. 如果使用自动同步，请测试公开仓库，以及有代表性的私有或 Internal 仓库用户，包括源端邮箱不可用的成员。未使用自动同步时，应测试每个已分配 OpenCore 群组和一个群组外用户。 ## 故障排除 | 症状 | 检查项 | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | 验证返回 401 | 替换无效或已过期的 GitHub access token。 | | 验证返回 403 | 授予 token 对仓库与所需 API 的访问权限。对于受 SAML 保护的组织，确认 token 已获该组织授权。 | | Owner 或仓库返回 404 | 检查准确的 owner 与仓库名、token 可见性，以及部署级 GitHub Enterprise API base URL。 | | 逗号分隔的仓库只有部分被索引 | 连接器会记录无法访问的仓库名；只要至少一个已配置仓库有效，它就可能继续。逐一检查名称与 token 授权；不要把部分成功当成完整范围验证。 | | **全部**遗漏了仓库 | 先确认 owner 类型。组织 owner 会列举 token 可见的组织仓库，应检查实际列表与 token 访问。用户 owner 使用 `/users/{user}/repos`，只返回公开仓库；请在**指定仓库**中明确添加所需用户私有仓库。 | | 首次运行没有产生文档 | 第一个 checkpoint 只缓存仓库 ID。继续运行，让 PR、issue 与文件阶段执行。 | | README 被索引但源码没有 | 这是预期行为。**包含文档**使用文档扩展名/文件名 allowlist 与默认分支，并不是通用源码索引器。 | | 超大型仓库缺少部分文档 | 检查连接器失败中是否有 GitHub 递归树截断，并检查 1,000,000 字节限制、被排除的路径分段、不支持的扩展名或非文本内容。 | | 最近变更的条目出现在名义轮询窗口外 | PR 与 issue 轮询使用三小时起点重叠和一天终点扩展。仓库文件处理使用 `pushed_at`，它可能因为向任意分支推送而变化。 | | 自动同步拒绝了合法源端用户 | 确认仓库可见性映射、team/collaborator 成员关系，以及 GitHub 是否返回与 OpenCore 账号匹配的可用邮箱。如果无法安全解析源端身份，请改用明确的 OpenCore 私有群组。 | | 用户可以搜索自己无法在 GitHub 打开的内容 | 自动同步已禁用/不可用，或连接器被设为公开/分配范围过宽。受支持时启用并测试自动同步，否则应使用更窄的 OpenCore 私有群组与仓库范围。 | ## 相关页面 * [连接器与索引](/opencore/knowledge/connectors) * [索引设置](/opencore/knowledge/index-settings)