附录 A：GitHub（通过 OAuth 应用程序）源操作
本附录提供有关 CodePipeline 中 GitHub 操作（通过 OAuth 应用程序）的信息。
注意
虽然我们不建议使用 GitHub（通过 OAuth 应用程序）操作，但具有 GitHub（通过 OAuth 应用程序）操作的现有管道将继续正常运行，不会产生任何影响。对于具有 GitHub（通过 OAuth 应用程序）操作的管道，CodePipeline 使用基于 OAuth 的令牌连接您的 GitHub 存储库。相比之下，GitHub 操作（通过 GitHub 应用程序）使用连接资源将 AWS 资源关联到您的 GitHub 存储库。该连接资源使用基于应用的令牌进行连接。有关将管道更新为使用连接的建议 GitHub 操作的更多信息，请参阅将 GitHub（通过 OAuth 应用程序）源操作更新为 GitHub（通过 GitHub 应用程序）源操作。有关基于 OAuth 的 GitHub 访问与基于应用的 GitHub 访问对比的更多信息，请参阅 https://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps
为了与 GitHub 集成，CodePipeline 对您的管道使用 GitHub OAuth 应用程序。对具有 GitHub（通过 OAuth 应用程序）源操作的管道，CodePipeline 使用 Webhook 来管理更改检测。
注意
在 CloudFormation 中配置 GitHub（通过 GitHub 应用程序）源操作时，无需包含任何 GitHub 令牌信息或添加 Webhook 资源。您可以按照 CloudFormation 用户指南 中 AWS::CodeStarConnections::Connection 所示，配置连接资源。
此参考包含以下适用于 GitHub（通过 OAuth 应用程序）操作的部分：
-
有关如何将 GitHub（通过 OAuth 应用程序）源操作和 Webhook 添加到管道的信息，请参阅添加 GitHub（通过 OAuth 应用程序）源操作。
-
有关 GitHub（通过 OAuth 应用程序）源操作的配置参数和 YAML/JSON 示例片段的信息，请参阅 GitHub（通过 OAuth 应用程序）源操作参考。
重要
创建 CodePipeline Webhook 时，请勿使用您自己的凭证，也不要在多个 Webhook 中重复使用相同的密钥令牌。为获得最佳安全性，请为您创建的每个 Webhook 生成一个唯一的密钥令牌。密钥令牌是您提供的任意字符串，GitHub 用它来计算和签署发送到 CodePipeline 的 Webhook 有效载荷，以保护 Webhook 有效载荷的完整性和真实性。使用您自己的凭证或在多个 Webhook 中重复使用相同的令牌可能会导致安全漏洞。
注意
如果提供了密钥令牌，则会在响应中对其进行编辑。
添加 GitHub（通过 OAuth 应用程序）源操作
您可以通过以下方式，将 GitHub（通过 OAuth 应用程序）源操作添加到 CodePipeline：
-
使用 CodePipeline 控制台创建管道向导（创建自定义管道（控制台））或编辑操作页面，选择 GitHub 提供方选项。控制台会创建一个 Webhook，用于在源发生变更时启动您的管道。
-
使用 CLI 添加
GitHub操作的操作配置并创建其他资源，如下所示：-
使用 GitHub（通过 OAuth 应用程序）源操作参考中的
GitHub示例操作配置来创建操作，如创建管道（CLI） 中所示。 -
禁用定期检查并手动创建更改检测，因为更改检测方法默认通过轮询源来启动管道。您将轮询管道迁移到 Webhook，以执行 GitHub（通过 OAuth 应用程序）操作。
-
GitHub（通过 OAuth 应用程序）源操作参考
注意
虽然我们不建议使用 GitHub（通过 OAuth 应用程序）操作，但具有 GitHub（通过 OAuth 应用程序）操作的现有管道将继续正常运行，不会产生任何影响。对于具有 GitHub（通过 OAuth 应用程序）源操作的管道，CodePipeline 使用基于 OAuth 的令牌连接您的 GitHub 存储库。相比之下，新 GitHub 操作（通过 GitHub 应用程序）使用连接资源将 AWS 资源关联到您的 GitHub 存储库。该连接资源使用基于应用的令牌进行连接。有关将管道更新为使用连接的建议 GitHub 操作的更多信息，请参阅将 GitHub（通过 OAuth 应用程序）源操作更新为 GitHub（通过 GitHub 应用程序）源操作。
在配置的 GitHub 存储库和分支上进行新提交时触发管道。
为了与 GitHub 集成，CodePipeline 对您的管道使用 OAuth 应用程序或个人访问令牌。如果您使用控制台创建或编辑管道，CodePipeline 会创建 GitHub Webhook，用于在存储库中发生更改时启动您的管道。
您必须已经创建 GitHub 账户和存储库，然后才能通过 GitHub 操作连接该管道。
如果要限制 CodePipeline 对存储库的访问权限，请创建一个 GitHub 账户，并且仅授权该账户访问那些您希望与 CodePipeline 集成的存储库。当您配置 CodePipeline 对管道中的源阶段使用 GitHub 存储库时，应使用该账户。
有关更多信息，请参阅 GitHub 网站上的 GitHub 开发人员文档
操作类型
-
类别：
Source -
拥有者：
ThirdParty -
提供方：
GitHub -
版本：
1
配置参数
- 所有者
-
必需：是
拥有 GitHub 存储库的 GitHub 用户或组织的名称。
- 存储库
-
必需：是
要在其中检测源更改的存储库的名称。
- 分支
-
必需：是
要在其中检测源更改的分支的名称。
- OAuthToken
-
必需：是
表示允许 CodePipeline 在您 GitHub 存储库上执行操作的 GitHub 身份验证令牌。条目始终显示为四个星号的掩码。它表示以下值：
-
当您使用控制台创建管道时，CodePipeline 会使用 OAuth 令牌注册 GitHub 连接。
-
使用 AWS CLI 创建管道时，您可以在此字段中传递 GitHub 个人访问令牌。将星号 (****) 替换为从 GitHub 复制的个人访问令牌。在运行
get-pipeline查看操作配置时，将显示此值的四星号掩码。 -
在使用 CloudFormation 模板创建管道时，必须先将令牌作为密码存储在 AWS Secrets Manager 中。您应该动态引用 Secrets Manager 中存储的密钥，将其作为此字段的值包含在内，如
{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}。
有关 GitHub 范围的更多信息，请参阅 GitHub 网站上的 GitHub 开发人员 API 参考
。 -
- PollForSourceChanges
-
必需：否
PollForSourceChanges控制 CodePipeline 是否轮询 GitHub 存储库中的源更改。我们建议您改为使用 Webhook 来检测源更改。有关配置 Webhook 的更多信息，请参阅将轮询管道迁移到 Webhook [GitHub（通过 OAuth 应用程序）源操作]（CLI） 或更新推送事件的管道 [GitHub（通过 OAuth 应用程序）源操作]（CloudFormation 模板）。重要
如果您要配置 Webhook，则必须将
PollForSourceChanges设置为false以避免重复的管道执行。此参数的有效值：
-
True：如果设置此值，则 CodePipeline 将轮询您存储库中的源更改。注意
如果省略
PollForSourceChanges，则 CodePipeline 默认轮询您存储库中的源更改。此行为与将PollForSourceChanges设置为true相同。 -
False：如果设置此值，则 CodePipeline 不轮询您存储库中的源更改。如果您打算配置 Webhook 来检测源更改，请使用此设置。
-
输入构件
-
构件数：
0 -
描述：输入构件不适用于此操作类型。
输出构件
-
构件数：
1 -
描述：此操作的输出构件是一个 ZIP 文件，其中包含在提交时，指定作为管道执行的源修订的已配置存储库和分支的内容。从存储库生成的构件是针对 GitHub 操作的输出构件。源代码提交 ID 在 CodePipeline 中显示为所触发管道执行的源修订。
输出变量
配置后，此操作会生成变量，该变量可由管道中下游操作的操作配置引用。此操作生成的变量可视为输出变量，即使操作没有命名空间也是如此。您可以使用命名空间配置操作，以使这些变量可用于下游操作的配置。
有关 CodePipeline 中变量的更多信息，请参阅变量参考。
- CommitId
-
触发管道执行的 GitHub 提交 ID。提交 ID 是提交的完整 SHA。
- CommitMessage
-
与触发管道执行的提交相关联的描述消息（如果有）。
- CommitUrl
-
触发管道的提交的 URL 地址。
- RepositoryName
-
发出创建触发管道的提交的 GitHub 存储库名称。
- BranchName
-
进行源更改的 GitHub 存储库的分支名称。
- AuthorDate
-
授权提交的日期，采用时间戳格式。
- CommitterDate
-
进行提交的日期，采用时间戳格式。
操作声明（GitHub 示例）
连接到 GitHub (OAuth)
第一次使用控制台将 GitHub 存储库添加到管道时，您需要授权 CodePipeline 访问您的存储库。令牌需要以下 GitHub 范围：
-
repo范围，用于完全控制从公有和私有存储库读取项目并将项目提取到管道中的过程。 -
admin:repo_hook范围，用于完全控制存储库挂钩。
使用 CLI 或 CloudFormation 模板时，您必须为已在 GitHub 中创建的个人访问令牌提供值。
另请参阅
下列相关资源在您使用此操作的过程中会有所帮助。
-
AWS CloudFormation 用户指南 AWS::CodePipeline::Webhook 的资源引用：这包括 CloudFormation 中资源的字段定义、示例和代码片段。
-
AWS CloudFormation 用户指南 AWS::CodeStar::GitHubRepository 的资源引用：这包括 CloudFormation 中资源的字段定义、示例和代码片段。
-
教程：创建使用 AWS Device Farm 构建和测试 Android 应用程序的管道：本教程提供了一个示例构建规范文件和示例应用程序，用于创建具有 GitHub 源的管道。它使用了 CodeBuild 和 AWS Device Farm 来构建和测试一款 Android 应用。
