定制 Jenkins 在 GitHub 中的状态信息
了解如何个性化 Jenkins 向 GitHub 发送的构建状态和上下文
关键亮点
- 使用 GitHub Plugin 和 Checks Plugin： Jenkins 与 GitHub 集成主要依赖于 GitHub Plugin 和 GitHub Checks Plugin，它们允许 Jenkins 向 GitHub 的 Commit Status API 和 Checks API 发送构建状态。
- 定制状态上下文： 可以通过 Jenkins 的配置或 Jenkinsfile 来修改默认的状态上下文（例如 "continuous-integration/jenkins/branch"），以便在 GitHub 中显示更具描述性的状态检查。
- 个人访问令牌： 为了让 Jenkins 能够向 GitHub 发送状态更新，需要生成一个具有适当权限（通常是
repo:status）的 GitHub 个人访问令牌，并在 Jenkins 中进行配置。
Jenkins 与 GitHub 集成概述
Jenkins 作为一款流行的开源自动化服务器，与 GitHub 的集成是持续集成/持续交付 (CI/CD) 工作流程中的关键一环。通过这种集成，Jenkins 可以在 GitHub 仓库发生代码提交、拉取请求等事件时自动触发构建，并将构建结果（成功、失败、进行中等）反馈回 GitHub，显示在相应的提交或拉取请求页面上。这种反馈机制对于团队协作、代码质量控制和加速开发流程至关重要。
GitHub 提供了 Commit Status API 和 Checks API，允许外部服务（如 CI/CD 工具）向 GitHub 提交关于特定提交的状态信息。默认情况下，Jenkins 使用 GitHub Plugin 向 Commit Status API 发送状态更新，其默认的上下文通常显示为 "continuous-integration/jenkins/branch" 或类似的标识符。虽然这提供了基本的构建状态信息，但在复杂的项目中，可能需要更精细的状态报告，例如区分不同的构建阶段（编译、测试、部署）或集成其他外部检查工具的结果。
为了实现更灵活和定制化的状态显示，可以利用 Jenkins 的相关插件和配置选项来修改默认行为，或者通过直接调用 GitHub API 来创建自定义的状态检查。
配置 Jenkins 插件
安装必要的插件
要实现 Jenkins 与 GitHub 的集成并定制状态信息，首先需要确保 Jenkins 中安装了以下关键插件：
- GitHub Plugin: 这个插件提供了 Jenkins 与 GitHub 项目集成的核心功能，包括触发构建、管理凭据以及发送基本的提交状态。
- GitHub Branch Source Plugin: 对于多分支管道项目，这个插件是管理和发现 GitHub 仓库分支和拉取请求的推荐方式。
- GitHub Checks Plugin: 这个插件利用 GitHub Checks API，提供比 Commit Status API 更丰富和详细的状态检查功能，允许创建具有更多上下文和详细信息的检查报告。
这些插件可以通过 Jenkins 的插件管理界面进行安装。安装完成后，通常需要重启 Jenkins 使其生效。
配置 GitHub 凭据
Jenkins 需要通过身份验证才能与 GitHub API 进行交互，发送状态更新。最安全和推荐的方式是使用 GitHub 个人访问令牌（Personal Access Token）。
在 GitHub 中生成个人访问令牌时，需要为其授予适当的权限。为了设置提交状态，所需的最小权限是 repo:status。如果使用 Checks API，可能需要额外的权限，具体取决于 Checks Plugin 的要求。
生成令牌后，需要在 Jenkins 中配置这些凭据。通常在“Manage Jenkins” -> “Manage Credentials”中添加一个“Secret text”类型的凭据，将个人访问令牌作为 Secret 进行存储，并指定一个 ID 以便在 Jenkins 配置或 Jenkinsfile 中引用。
图：Jenkins 和 GitHub 集成示意图
配置 Jenkins 项目
在 Jenkins 项目的配置中，需要指定与 GitHub 仓库的连接。对于自由式项目，可以在“Source Code Management”部分选择 Git，并填写 GitHub 仓库的 URL。对于管道项目，可以直接在 Jenkinsfile 中定义 SCM。
配置 GitHub 集成时，通常需要启用“Build when a change is pushed to GitHub”等选项，以便 GitHub 的 Webhook 能够触发 Jenkins 构建。同时，在“Post-build Actions”或 Jenkinsfile 的适当位置，需要配置 Jenkins 向 GitHub 发送构建状态。
使用 GitHub Plugin 设置提交状态
对于自由式或声明式管道项目，可以在 Post-build Actions 中添加“Set GitHub commit status (universal)”步骤。在这个步骤中，可以配置在不同构建结果（成功、失败、不稳定等）下发送的状态信息。默认情况下，上下文可能是 “continuous-integration/jenkins/branch”，但某些配置或更新版本的插件可能允许直接修改这个上下文标签。
使用 GitHub Checks Plugin 创建自定义检查
GitHub Checks Plugin 提供了更强大的定制能力。通过这个插件，可以在 Jenkinsfile 中更细粒度地控制创建哪些检查、它们的名称、状态以及关联的详细信息和链接。这使得在 GitHub 中显示多个状态检查成为可能，每个检查代表管道中的一个特定阶段或外部工具的结果。
pipeline {
agent any
stages {
stage('Build') {
steps {
echo 'Building...'
// Simulate build process
script {
manager.createCheck('Build Status', 'PENDING')
}
}
}
stage('Test') {
steps {
echo 'Testing...'
// Simulate test process
script {
manager.updateCheck('Build Status', 'SUCCESS', 'Build and tests passed')
}
}
}
}
}
在上面的 Jenkinsfile 片段中，使用了 Checks API 相关的步骤（createCheck, updateCheck）来创建和更新名为“Build Status”的检查。通过修改这些步骤的参数，可以完全定制在 GitHub 中显示的状态检查的名称和描述。
定制状态上下文和描述
要改变默认的 "continuous-integration/jenkins/branch" 上下文，有几种方法可以尝试，具体取决于你使用的 Jenkins 版本、插件版本以及项目类型（自由式、声明式管道、脚本化管道）。
通过插件配置修改上下文
一些插件（如 GitHub Branch Source Plugin 结合 GitHub Custom Notification Context SCM Behaviour）允许在项目或全局配置中定义自定义的通知上下文。在多分支管道项目的配置中，可以在“Branch Sources” -> “GitHub” -> “Behaviors”下添加“Custom GitHub Notification Context”行为，并指定一个自定义的标签。
此外，GitHub Checks Plugin 允许在 Jenkinsfile 中定义自定义的检查名称，这实际上是 Checks API 中的“name”或“context”字段，取代了 Commit Status API 中单一的上下文概念。
使用 Jenkinsfile 进行定制
在 Jenkinsfile 中，特别是在脚本化管道中，可以更灵活地控制向 GitHub 发送的状态信息。可以通过直接调用 GitHub API 来实现完全自定义的状态更新。
使用 curl 命令调用 GitHub Status API
一种直接的方法是在 Jenkinsfile 中使用 curl 命令调用 GitHub 的 Commit Status API。这需要将 GitHub 个人访问令牌存储为 Jenkins 凭据，并在 Jenkinsfile 中安全地访问它。
stage('Update GitHub Status') {
steps {
script {
def githubApiUrl = "https://api.github.com/repos/${ORG_NAME}/${REPO_NAME}/statuses/${GIT_COMMIT}"
def token = 'YOUR_GITHUB_TOKEN' // Replace with actual credential lookup
def status = 'success' // or 'failure', 'pending', 'error'
def context = 'my-custom-check'
def description = 'Build completed successfully'
def targetUrl = "${BUILD_URL}"
sh "curl -X POST -H \"Content-Type: application/json\" -H \"Authorization: token ${token}\" -d '{\"state\": \"${status}\", \"context\": \"${context}\", \"description\": \"${description}\", \"target_url\": \"${targetUrl}\"}' ${githubApiUrl}"
}
}
}
在上面的示例中，${ORG_NAME}、${REPO_NAME} 和 ${GIT_COMMIT} 是 Jenkins 提供的环境变量。你需要替换 'YOUR_GITHUB_TOKEN' 为从 Jenkins 凭据存储中获取的实际令牌。通过修改 context、description 和 state 变量的值，可以完全定制在 GitHub 中显示的状态信息。
使用 Checks API 通过 Jenkinsfile
如果使用了 GitHub Checks Plugin，可以直接在 Jenkinsfile 中使用该插件提供的步骤来创建和管理 Checks。这通常比直接调用 API 更方便和集成度更高。
pipeline {
agent any
stages {
stage('Static Analysis') {
steps {
script {
def checkRun = manager.createCheck('Static Analysis', 'IN_PROGRESS')
// Run static analysis tools
// ...
// Update check status based on results
if (analysisFailed) {
checkRun.update('COMPLETED', 'FAILURE', 'Static analysis found issues')
} else {
checkRun.update('COMPLETED', 'SUCCESS', 'Static analysis passed')
}
}
}
}
stage('Unit Tests') {
steps {
script {
def checkRun = manager.createCheck('Unit Tests', 'IN_PROGRESS')
// Run unit tests
// ...
// Update check status based on results
if (testsFailed) {
checkRun.update('COMPLETED', 'FAILURE', 'Unit tests failed')
} else {
checkRun.update('COMPLETED', 'SUCCESS', 'Unit tests passed')
}
}
}
}
}
}
这个 Jenkinsfile 示例展示了如何为静态分析和单元测试创建独立的 GitHub Checks，并在各自的阶段完成后更新其状态。这允许在 GitHub 的拉取请求页面上清晰地看到不同检查的结果。
GitHub Status API 与 Checks API 的对比
了解 GitHub Status API 和 Checks API 之间的区别有助于选择最适合你需求的方法。
雷达图展示了 GitHub Commit Status API 和 Checks API 在定制能力、提供详细信息、支持多个状态、与 Jenkins 集成以及易用性方面的比较。Checks API 在定制能力、详细信息和支持多个状态方面通常优于 Commit Status API，而 Commit Status API 在与现有 Jenkins 插件的集成和基本易用性方面可能更具优势。
下表总结了两者的一些关键区别：
| 特性 | Commit Status API | Checks API |
|---|---|---|
| 显示位置 | 提交旁边或拉取请求的对话选项卡 | 拉取请求的 Checks 选项卡 |
| 状态类型 | pending, success, failure, error | queued, in_progress, completed (结果可以是 success, failure, neutral, cancelled, timed_out, action_required) |
| 详细信息 | 简短的描述和目标 URL | 更丰富的文本描述、摘要、单独的步骤和注解 |
| 多个状态 | 每个上下文一个状态 | 可以为每个提交创建多个检查 |
| 集成方式 | 相对简单的 API 调用或 Jenkins 插件 | 更复杂的 API，通常通过 GitHub App 或 Jenkins 插件集成 |
如果你只需要为整个构建提供一个整体状态，并且习惯于使用 Jenkins 的 Post-build Actions，Commit Status API 可能就足够了。然而，如果你需要更详细的状态报告、为不同的构建阶段显示独立的状态，或者集成静态分析、测试覆盖率等工具的结果，Checks API 是更强大和灵活的选择。
进一步定制选项
定制链接的目标 URL
默认情况下，Jenkins 发送到 GitHub 的状态通常会链接到 Jenkins 中相应的构建页面。如果你想链接到其他页面，例如测试报告或外部报告页面，可以在发送状态更新时指定不同的 target_url。
使用环境变量和 Token Macro
在定制状态描述和上下文时，可以使用 Jenkins 提供的环境变量（如 ${BUILD_NUMBER}, ${JOB_NAME}, ${GIT_COMMIT}）和 Token Macro 插件提供的宏来动态生成信息，使其更具描述性。
创建自定义的状态消息
除了修改上下文，还可以定制状态的描述信息。一些 Jenkins 插件允许在配置中填写自定义的描述模板，或者在 Jenkinsfile 中通过 API 调用/插件步骤来设置描述文本。
视频：GitHub Checks API Plugin 原型演示
这个视频展示了 GitHub Checks API Plugin 的早期原型，说明了如何利用 Checks API 在 GitHub 中显示更详细和结构化的构建检查信息，这有助于更好地理解如何通过 Jenkins 定制在 GitHub 中的显示效果。
故障排除
在配置 Jenkins 向 GitHub 发送状态时，可能会遇到一些问题。以下是一些常见的故障排除步骤：
- 检查 GitHub 个人访问令牌： 确保令牌具有正确的权限（至少是
repo:status）。检查令牌是否已过期或被撤销。 - 验证 Jenkins 凭据： 确保在 Jenkins 中正确配置了 GitHub 凭据，并且 Jenkins 项目能够访问这些凭据。
- 检查 GitHub Webhook 配置： 如果你的 Jenkins 构建是由 GitHub Webhook 触发的，确保 Webhook 配置正确，并且 Jenkins 能够接收来自 GitHub 的请求。
- 查看 Jenkins 日志： Jenkins 的构建日志通常包含与 GitHub 通信相关的错误信息，仔细查看日志可以帮助定位问题。
- 检查 GitHub API 速率限制： 大量的 API 请求可能会导致达到 GitHub 的 API 速率限制，这可能会影响状态更新。
- 插件兼容性： 确保使用的 Jenkins 插件与你的 Jenkins 版本和 GitHub 兼容。
常见问题 (FAQ)
推荐阅读
- 如何配置 Jenkins GitHub 插件？
- 如何在 Jenkins 中使用 GitHub Checks API？
- 如何在 Jenkins 声明式管道中设置 GitHub 状态？
- 如何定制 GitHub 提交状态的上下文？
参考资料
Last updated May 20, 2025