GitHub

GitHub 是一项基于 Web 的软件开发托管服务，提供带有版本控制的代码存储和管理服务。您可以使用 Amazon Kendra 为 GitHub Enterprise Cloud（SaaS）和 GitHub Enterprise Server（本地部署）存储库文件、议题和拉取请求、议题和拉取请求评论以及议题和拉取请求评论附件编制索引。您也可以选择包括或排除某些文件。

注意

Amazon Kendra 现在支持升级后的 GitHub 连接器。

控制台已为您自动升级。您在控制台中新建的所有连接器都将使用升级后的架构。如果您使用 API，则现在必须使用 TemplateConfiguration 对象而不是 GitHubConfiguration 对象来配置您的连接器。

使用旧版控制台或旧版 API 架构配置的连接器仍可照常运行，但您将无法编辑或更新它们。如果要编辑或更新连接器配置，必须新建一个连接器。

我们建议您将连接器工作流程迁移至升级后的版本。使用旧版架构配置的连接器的支持预计将在 2024 年 6 月前终止。

您可以使用 Amazon Kendra 控制台或 TemplateConfiguration API 将 Amazon Kendra 连接到您的 GitHub 数据来源。

要对 Amazon Kendra GitHub 数据来源连接器进行故障排除，请参阅。

支持的功能

Amazon Kendra GitHub 数据来源连接器支持以下功能：

字段映射
用户访问控制
包含/排除筛选条件
完整和增量内容同步
虚拟私有云（VPC）

先决条件

在使用 Amazon Kendra 为 GitHub 数据来源编制索引之前，请先在 GitHub 和 AWS 账户内进行这些更改。

在 GitHub 中，请确保：

创建了一个拥有 GitHub 组织管理权限的 GitHub 用户。
已在 GitHub 中配置了个人访问令牌，用作您的身份验证凭证。请参阅有关创建个人访问令牌的 GitHub 文档。

注意
我们建议您定期刷新或轮换您的凭证和密码。为了安全起见，请仅提供必要的访问权限级别。我们建议不要跨数据来源以及连接器版本 1.0 和 2.0（如果适用）重复使用凭证和密钥。
推荐：为身份验证凭证配置了 OAuth 令牌。使用 OAuth 令牌可获得更好的 API 限制和连接器性能。请参阅有关 OAuth 身份验证的 GitHub 文档。
已记下您使用的 GitHub 服务类型的 GitHub 主机 URL。例如，GitHub 云的主机 URL 可能是 https://api.github.com，GitHub 服务器的主机 URL 可能是 https://on-prem-host-url/api/v3/。
已记下您的 GitHub 组织名称、您要连接的 GitHub 企业云（SaaS）账户或 GitHub 企业服务器（本地）账户。您可以登录 GitHub 桌面并在个人资料图片下拉列表下方选择您的组织来找到您的组织名称。
可选（仅限服务器）：生成 SSL 证书并复制存储在 Amazon S3 存储桶中的证书的路径。如果您需要安全的 SSL 连接，则可以使用它来连接 GitHub。您只需使用 OpenSSL 在任何计算机上生成自签名 X509 证书。有关使用 OpenSSL 创建 X509 证书的示例，请参阅创建并签署 X509 证书。
添加了以下权限：

适用于 GitHub 企业云（SaaS）
- repo:status – 授予公有和私有存储库中的提交状态的读/写权限。只有在向其他用户或服务授予访问私有存储库提交状态的权限，但不授予访问代码的权限时，才需要使用此范围。
- repo_deployment – 授予访问公有和私有存储库的部署状态的权限。只有在向其他用户或服务授予访问部署状态的权限，但不授予访问代码的权限时，才需要使用此范围。
- public_repo – 限制对公有存储库的访问。这包括对公有存储库的代码、提交状态、存储库项目、协作者和部署状态以及对组织的读/写权限。此外还需要为公有存储库添加星标。
- repo:invite – 授予接受/拒绝在存储库上开展协作的邀请的能力。只有在向其他用户或服务授予使用邀请的权限，但不授予访问代码的权限时，才需要使用此范围。
- security_events – 授权：在代码扫描 API 中读取和写入安全事件的权限。只有在向其他用户或服务授予访问安全事件的权限，但不授予访问代码的权限时，才需要使用此范围。
- read:org – 对组织成员资格、组织项目和团队成员资格的只读访问权限。
- user:email – 授予对用户电子邮件地址的读取访问权限。Amazon Kendra 爬取 ACL 所必需。
- user:follow – 授予关注或取消关注其他用户的权限。Amazon Kendra 爬取 ACL 所必需。
- read:user – 授予读取用户个人资料数据的访问权限。Amazon Kendra 爬取 ACL 所必需。
- workflow – 授予添加和更新 GitHub 操作工作流程文件的能力。如果同一存储库中的另一个分支上存在相同的文件（路径和内容均相同），则可以在没有此范围的情况下提交工作流文件。
有关更多信息，请参阅 GitHub 文档中的 Scopes for OAuth apps。

适用于 GitHub 企业服务器（本地部署）
- repo:status – 授予公有和私有存储库中的提交状态的读/写权限。只有在向其他用户或服务授予访问私有存储库提交状态的权限，但不授予访问代码的权限时，才需要使用此范围。
- repo_deployment – 授予访问公有和私有存储库的部署状态的权限。只有在向其他用户或服务授予访问部署状态的权限，但不授予访问代码的权限时，才需要使用此范围。
- public_repo – 限制对公有存储库的访问。这包括对公有存储库的代码、提交状态、存储库项目、协作者和部署状态以及对组织的读/写权限。此外还需要为公有存储库添加星标。
- repo:invite – 授予接受/拒绝在存储库上开展协作的邀请的能力。只有在向其他用户或服务授予使用邀请的权限，但不授予访问代码的权限时，才需要使用此范围。
- security_events – 授权：在代码扫描 API 中读取和写入安全事件的权限。只有在向其他用户或服务授予访问安全事件的权限，但不授予访问代码的权限时，才需要使用此范围。
- read:user – 授予读取用户个人资料数据的访问权限。Amazon Q 企业版爬取 ACL 所必需。
- user:email – 授予对用户电子邮件地址的读取访问权限。Amazon Q 企业版爬取 ACL 所必需。
- user:follow – 授予关注或取消关注其他用户的权限。Amazon Q 企业版爬取 ACL 所必需。
- site_admin – 授予站点管理员访问 GitHub Enterprise Server 管理 API 端点的权限。
- workflow – 授予添加和更新 GitHub 操作工作流程文件的能力。如果同一存储库中的另一个分支上存在相同的文件（路径和内容均相同），则可以在没有此范围的情况下提交工作流文件。
有关更多信息，请参阅《GitHub Docs》中的 Scopes for OAuth apps，以及《GitHub Developer》中的 Understanding scopes for OAuth Apps。
在 GitHub 以及计划用于编制同一索引的其他数据来源中，已检查每个文档都是唯一的。您要用于编制索引的每个数据来源在所有数据来源中都不能包含相同的文档。文档 ID 对索引来说是全局性的，并且每个索引都必须是唯一的。

在 AWS 账户中，请确保：

已创建 Amazon Kendra 索引，如果使用 API，则记下索引 ID。
为您的数据来源创建了一个 IAM 角色，如果使用 API，请记下 IAM 角色的 ARN。

注意
如果您更改了身份验证类型和证书，则必须更新您的 IAM 角色才能访问正确的 AWS Secrets Manager 密钥 ID。
将您的 GitHub 身份验证凭证存储在 AWS Secrets Manager 密钥中，如果使用 API，请记下密钥的 ARN。

注意
我们建议您定期刷新或轮换您的凭证和密码。为了安全起见，请仅提供必要的访问权限级别。我们建议不要跨数据来源以及连接器版本 1.0 和 2.0（如果适用）重复使用凭证和密钥。

如果您没有现有的 IAM 角色或密钥，则在将 GitHub 数据来源连接到 Amazon Kendra 时，您可以使用控制台创建新的 IAM 角色和 Secrets Manager 密钥。如果您使用 API，则必须提供现有 IAM 角色和 Secrets Manager 密钥的 ARN 以及索引 ID。

连接说明

要将 Amazon Kendra 连接到 GitHub 数据来源，您必须提供 GitHub 数据来源的必要详细信息，这样 Amazon Kendra 才能访问您的数据。如果您还没有为 Amazon Kendra 配置 GitHub，请参阅先决条件。

Console

将 Amazon Kendra 连接到 GitHub

登录 AWS 管理控制台并打开 Amazon Kendra 控制台。
在左侧导航窗格中，选择索引，然后从索引列表中选择要使用的索引。

注意
您可以选择在索引设置下配置或编辑您的用户访问控制设置。
在入门页面上，选择添加数据来源。
在添加数据来源页面上，选择 GitHub 连接器，然后选择添加连接器。如果使用版本 2（如果适用），请选择带有“V2.0”标签的 GitHub 连接器。
在指定数据来源详细信息页面上输入以下信息：
1. 在名称和描述中，在数据来源名称中输入您的数据来源的名称。可以包含连字符，但不能包含空格。
2. （可选）描述：输入数据来源的描述信息。
3. 在默认语言中 – 选择用于筛选文档以编制索引的语言。除非另行指定，否则语言默认为英语。在文档元数据中指定的语言会覆盖所选语言。
4. 在标签中，对于添加新标签 – 添加用于搜索和筛选资源或跟踪 AWS 成本的标签。
5. 选择下一步。
在定义访问权限和安全性页面上，请输入以下信息：
1. GitHub 来源 - 选择 GitHub 企业云和 GitHub 企业服务器。
2. GitHub 主机 URL – GitHub 云的主机 URL 可以是 https://api.github.com，GitHub 服务器的主机 URL 可以是 https://on-prem-host-url/api/v3/。
3. 对于 GitHub 组织 - 输入您的 GitHub 组织名称。您可以在您的 GitHub 账户中找到您的组织信息。
  
  注意
  GitHub 连接器支持每个数据来源连接器实例爬取单个组织。
4. 授权 - 如果您有访问控制列表（ACL）并想将其用于访问控制，请选择是开启还是关闭文档的 ACL 信息。ACL 指定了用户和群组可以访问哪些文档。ACL 信息用于根据用户或其所在组对文档的访问权限来筛选搜索结果。有关更多信息，请参阅用户上下文筛选。
5. AWS Secrets Manager 密钥 – 选择现有密钥或创建新的 Secrets Manager 密钥来存储您的 GitHub 身份验证凭证。如果您选择创建新密钥，则会打开 AWS Secrets Manager 密钥窗口。
  1. 在创建 AWS Secrets Manager 密钥窗口中输入以下信息：
    1. 密钥名称 - 密钥的名称。前缀“AmazonKendra-GitHub-”会自动添加到您的密钥名称中。
    2. 对于 GitHub 令牌 – 输入您在 GitHub 中配置的身份验证凭证值。
  2. 保存并添加您的密钥。
6. 虚拟私有云（VPC）- 您可以选择使用 VPC。如果是这样，则必须添加子网和 VPC 安全组。
7. 身份爬网程序 – 指定是否激活 Amazon Kendra 的身份爬网程序。身份爬网程序使用文档的访问控制列表（ACL）信息，来根据用户或用户组对文档的访问权限筛选搜索结果。如果您的文档有 ACL 并选择使用 ACL，则还可以选择开启 Amazon Kendra 的身份爬网程序来配置搜索结果的用户上下文筛选。否则，如果关闭身份爬网程序，则可以公开搜索所有文档。如果您想对文档使用访问控制，但身份爬网程序已关闭，则可以选择使用 PutPrincipalMapping API 上传用户和组访问信息，以进行用户上下文筛选。
8. IAM 角色 - 选择现有 IAM 角色或创建新的 IAM 角色来访问您的存储库凭证和索引内容。
  
  注意
  用于编制索引的 IAM 角色不能用于数据来源。如果您不确定是否将现有角色用于编制索引或常见问题解答，为了避免出错，请选择创建新角色。
9. 选择下一步。
在配置同步设置页面上，请输入以下信息：
1. 选择存储库 – 选择对所有存储库进行爬取或选择。
  
  如果您选择爬取选择存储库，请为存储库添加名称，或者添加任何特定分支的名称。
2. 内容类型 – 从文件、问题、拉取请求等选择要爬取的内容类型。
3. 正则表达式模式 - 添加包含或排除某些文件的正则表达式模式。
4. 同步模式 - 选择在数据来源内容发生变化时更新索引的方式。首次将数据来源与 Amazon Kendra 同步时，默认情况下会爬取所有内容并编制索引。如果首次同步失败，即使您没有选择“完整同步”作为同步模式，也必须执行一次完整的数据同步。
  - 完整同步：每次数据来源与索引同步时，重新为所有内容编制索引，并替换已有内容。
  - 新增、修改的同步：每次数据来源与索引同步时，仅为新增和修改的内容编制索引。Amazon Kendra 可以利用数据来源自身的内容变更跟踪机制，仅为自上次同步以来发生变化的内容编制索引。
  - 新增、修改、删除的同步：每次数据来源与索引同步时，仅为新增、修改和删除的内容编制索引。Amazon Kendra 可以利用数据来源自身的内容变更跟踪机制，仅为自上次同步以来发生变化的内容编制索引。
5. 在同步运行计划的频率中 – 选择同步数据来源内容并更新索引的频率。
6. 选择下一步。
在设置字段映射页面上，请输入以下信息：
1. 默认数据来源字段 - 从 Amazon Kendra 生成的默认数据来源字段中选择要映射到索引的字段。
2. 添加字段 - 添加自定义数据来源字段以创建要映射到的索引字段名称和字段数据类型。
3. 选择下一步。
在查看和创建页面上，请检查输入的信息是否正确，然后选择添加数据来源。您也可以选择在此页面上编辑信息。成功添加数据来源后，您的数据来源将显示在数据来源页面上。

API

将 Amazon Kendra 连接到 GitHub

您必须使用 TemplateConfiguration API 指定数据来源架构的 JSON。您必须提供以下信息：

数据来源 – 当使用 TemplateConfiguration JSON 架构时，将数据来源类型指定为 GITHUB。当调用 CreateDataSource API 时，还要将数据来源指定为 TEMPLATE。
GitHub 类型 – 将类型指定为 SAAS 或 ON_PREMISE。
主机 URL – 指定 GitHub 主机 URL 或 API 端点 URL。例如，如果您使用 GitHub SaaS/企业云，主机 URL 可以是 https://api.github.com；如果您使用 GitHub 本地/Enterprise Server，主机 URL 可以是 https://on-prem-host-url/api/v3/。
组织名称 – 指定 GitHub 账户的组织名称。您可以登录 GitHub 桌面并在个人资料图片下拉列表下方选择您的组织来找到您的组织名称。
同步模式 - 指定当数据来源内容发生变化时 Amazon Kendra 更新索引的方式。首次将数据来源与 Amazon Kendra 同步时，默认情况下会爬取所有内容并编制索引。如果首次同步失败，即使您没有选择“完整同步”作为同步模式，也必须执行一次完整的数据同步。您可以选择：
- FORCED_FULL_CRAWL，每次数据来源与索引同步时，重新为所有内容编制索引，并替换已有内容。
- FULL_CRAWL，每次数据来源与索引同步时，仅为新增、修改和删除的内容编制索引。Amazon Kendra 可以利用数据来源自身的内容变更跟踪机制，仅为自上次同步以来发生变化的内容编制索引。
- CHANGE_LOG，每次数据来源与索引同步时，仅为新增和修改的内容编制索引。Amazon Kendra 可以利用数据来源自身的内容变更跟踪机制，仅为自上次同步以来发生变化的内容编制索引。
身份爬网程序 – 指定是否激活 Amazon Kendra 的身份爬网程序。身份爬网程序使用文档的访问控制列表（ACL）信息，来根据用户或用户组对文档的访问权限筛选搜索结果。如果您的文档有 ACL 并选择使用 ACL，则还可以选择开启 Amazon Kendra 的身份爬网程序来配置搜索结果的用户上下文筛选。否则，如果关闭身份爬网程序，则可以公开搜索所有文档。如果您想对文档使用访问控制，但身份爬网程序已关闭，则可以选择使用 PutPrincipalMapping API 上传用户和组访问信息，以进行用户上下文筛选。
密钥 Amazon 资源名称（ARN）– 提供包含您的 GitHub 账户身份验证凭证的 Secrets Manager 密钥的 Amazon 资源名称（ARN）。密钥必须使用具有以下键的 JSON 结构存储：
```
{
    "personalToken": "token"
}
```
IAM 角色 - 指定 RoleArn，以便调用 CreateDataSource 来向 IAM 角色提供访问您的 Secrets Manager 密钥的权限，以及为 GitHub 连接器和 Amazon Kendra 调用所需的公共 API 的权限。有关更多信息，请参阅 GitHub 数据来源的 IAM 角色。

您还可以添加以下可选功能：

虚拟私有云（VPC）- 指定 VpcConfiguration，以便调用 CreateDataSource。有关更多信息，请参阅配置 Amazon Kendra 以使用 Amazon VPC。

注意
如果您使用 GitHub 服务器，则必须使用 Amazon VPC 才能连接到您的 GitHub 服务器。
存储库筛选条件 – 按名称和分支名称筛选存储库。
文档/内容类型 – 指定是否爬取存储库文档、问题、问题评论、问题评论附件、拉取请求、拉取请求评论、拉取请求评论附件。
包含和排除筛选条件 – 指定是包含还是排除某些文件和文件夹。

注意
大多数数据来源使用正则表达式模式，即称为筛选条件的包含或排除模式。如果您指定包含筛选条件，则只会为与包含筛选条件匹配的内容编制索引。不会为任何与包含筛选条件不匹配的文档编制索引。如果您指定包含和排除筛选条件，则不会为与排除筛选条件匹配的文档编制索引，即使它们与包含筛选条件相匹配。
访问控制列表（ACL）- 如果您有 ACL 并想将其用于访问控制，请选择是否爬取文档的 ACL 信息。ACL 指定了用户和群组可以访问哪些文档。ACL 信息用于根据用户或其所在组对文档的访问权限来筛选搜索结果。有关更多信息，请参阅用户上下文筛选。
字段映射 - 选择将 GitHub 数据来源字段映射到 Amazon Kendra 索引字段。您可以包含文档字段、提交记录、问题、问题附件、问题评论、拉取请求、拉取请求附件以及拉取请求评论。有关更多信息，请参阅映射数据来源字段。

注意
文档正文字段或文档正文的等效字段是 Amazon Kendra 搜索文档时所必需的。您必须将数据来源中的文档正文字段名映射到索引字段名称 _document_body。其他所有字段均为可选字段。

有关要配置的其他重要 JSON 键的列表，请参阅 GitHub 模板架构。

了解更多

要了解有关将 Amazon Kendra 与 GitHub 数据来源集成的更多信息，请参阅：

借助 Amazon Kendra GitHub 连接器的强大功能，重新构想在 GitHub 存储库上进行搜索

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

Drupal

Gmail