Github 插件

该插件将 Jenkins 与 Github 项目集成。该插件目前有三个主要功能：

• 在 Jenkins 项目和 GitHub 之间创建超链接
• 通过解析来自 post-receive 钩子的 HTTP POST 请求触发作业，并可选择自动管理钩子设置
• 将构建状态结果报告回 GitHub，作为 提交状态（在 Stack Overflow 上有文档）
• 为其他插件提供基本功能

更改之间的超链接

Github 插件装饰 Jenkins 的"更改"页面，创建指向 Github 提交和问题页面的链接。它添加了一个侧边栏链接，链接回 Github 项目页面。

创建作业时，指定它连接到 git。在"Github 项目"下，输入：git@github.com:Person/Project.git。在"源代码管理"下选择 Git，并输入 git@github.com:Person/Project.git

GitHub 钩子触发 GITScm 轮询

此功能在GitHub 仓库中的 post-receive 钩子之后启用构建。此触发器仅针对每个传入的匹配仓库事件启动 git 插件内部轮询算法。

此触发器之前被命名为"当更改被推送到 GitHub 时构建"

使用方法

要使用此功能，可以使用不同的模式：

• 手动模式：URL 必须在每个项目中手动添加
• 自动模式：Jenkins 自动为每个项目注册 webhook

手动模式

在此模式下，您将负责向 GitHub 注册钩子 URL。点击 图标（在管理 Jenkins > 配置系统 > GitHub 下）以查看 Jenkins 中接收 post-commit POST 的 URL — 但通常 URL 的格式为 $JENKINS_BASE_URL/github-webhook/ — 例如：https://ci.example.com/jenkins/github-webhook/。

一旦您有了 URL，并将其添加为相关 GitHub 仓库的 webhook，继续步骤 3。

自动模式（Jenkins 自行管理作业的钩子）

在此模式下，Jenkins 将根据后台的项目配置自动向 GitHub 添加/删除钩子 URL。您需要指定 GitHub OAuth 令牌，以便 Jenkins 可以以您的身份登录来执行此操作。

步骤 1. 转到全局配置并添加 GitHub 服务器配置。

步骤 2.1. 在 GitHub 中创建您的个人访问令牌。

插件可以帮助您创建所有必需范围的令牌。转到高级 -> 管理其他 GitHub 操作 -> 将登录和密码转换为令牌

双因素认证

自动创建令牌不适用于 GitHub 双因素认证

您可以直接使用登录和密码在相应域中创建带有令牌的 "Secret text" 凭据，或从用户名和密码凭据创建。

步骤 2.2. 选择之前创建的带有 GitHub OAuth 令牌的"Secret Text"凭据。

令牌所需的范围

要能够管理钩子，您的令牌应具有 admin:org_hook 范围。

GitHub Enterprise

您还可以通过点击 自定义 GitHub API URL 复选框来重新定义 GitHub URL。 请注意，凭据会通过域要求的帮助按输入的 GH URL 进行过滤。因此，您可以在不同域中创建凭据，并只看到与预定义域匹配的凭据。

步骤 3. 完成配置后，转到您希望自动触发的每个作业的项目配置，并在"构建触发器"下简单勾选"GitHub hook trigger for GITScm polling"。这样，每次向仓库推送新内容时都会自动触发新的构建。

请注意，只有一个 URL，它接收所有仓库的所有 post-receive POST 请求。此 URL 的服务器端足够智能，可以根据提交内容确定需要触发哪些项目。

安全影响

此插件要求您有一个从 GitHub 可访问的 HTTP URL，这意味着它可以从整个互联网访问。因此，考虑到可能存在恶意的假 post-receive POST 请求，它的实现非常谨慎。为了应对这种情况，在收到 POST 请求后，Jenkins 将与 GitHub 通信以确保推送确实发生。

防火墙内的 Jenkins

如果您的 Jenkins 在防火墙内运行，不能直接从互联网访问，此插件允许您在自动模式下指定任意端点 URL 作为覆盖。插件将假设您已设置反向代理或其他方式，以便来自 GitHub 的 POST 请求将被路由到 Jenkins。

钩子故障排除

如果您设置了这些但构建未被触发，请检查以下事项：

• 点击相关 GitHub 仓库上的"admin"按钮，确保 post-receive 钩子存在。
  • 如果不存在，确保您在 Jenkins 系统配置页面中设置了正确的凭据。
• 另外，启用日志记录以下类名
  • com.cloudbees.jenkins.GitHubPushTrigger
  • org.jenkinsci.plugins.github.webhook.WebhookManager
  • com.cloudbees.jenkins.GitHubWebHook
    您将看到 Jenkins 尝试安装 post-receive 钩子的日志。
• 从 GitHub UI 点击"Test hook"按钮，查看 Jenkins 是否收到有效负载。

使用缓存处理 GitHub 请求

每个 GitHub 服务器配置 创建自己的 GitHub 客户端与 API 交互。默认情况下，它使用缓存（限制为 20MB）来加速数据获取过程并减少速率限制消耗。您可以在此配置项的"高级"部分更改缓存限制值。如果您设置为 0，则此功能将对此（且仅此）配置禁用。

附加信息：

• 该插件现在主要功能是只从 GitHub 提供钩子。然后它开始使用 git 插件来获取源代码。
• 它同时适用于公共和企业版 GitHub
• 插件有一些限制

Jenkins 和 GitHub 之间可能存在的问题

Windows:

• 在 Windows 中，Jenkins 将使用运行它的用户的 SSH 密钥，该密钥位于 %USERPROFILE%.ssh 文件夹中（在 XP 上，路径是 C:\Documents and Settings\USERNAME.ssh，在 Windows 7 上是 C:\Users\USERNAME.ssh）。因此，你需要强制 Jenkins 以配置了 SSH 密钥的用户身份运行。为此，右击"我的电脑"，点击"管理"。点击"服务"。找到 Jenkins，右击并选择"属性"。在"登录"选项卡下，选择 Jenkins 将要运行的用户，并输入用户名和密码（这是必需的）。然后通过在服务窗口中右击 Jenkins 并点击"重新启动"来重启 Jenkins 服务。
• Jenkins 不支持带密码短语的 SSH 密钥。因此，如果你在初始 GitHub 配置时设置了密码短语，请重新运行配置并不要设置密码短语。

Pipeline 示例

设置提交状态

这段代码将为自定义仓库设置提交状态，包括配置的上下文和消息（你也可以用同样的方式定义反向引用）

void setBuildStatus(String message, String state) {
  step([
      $class: "GitHubCommitStatusSetter",
      reposSource: [$class: "ManuallyEnteredRepositorySource", url: "https://github.com/my-org/my-repo"],
      contextSource: [$class: "ManuallyEnteredCommitContextSource", context: "ci/jenkins/build-status"],
      errorHandlers: [[$class: "ChangingBuildStatusErrorHandler", result: "UNSTABLE"]],
      statusResultSource: [ $class: "ConditionalStatusResultSource", results: [[$class: "AnyBuildResult", message: message, state: state]] ]
  ]);
}

setBuildStatus("Build complete", "SUCCESS");

更复杂的示例（可用于 pipeline 中的多个 SCM 源）

def getRepoURL() {
  sh "git config --get remote.origin.url > .git/remote-url"
  return readFile(".git/remote-url").trim()
}

def getCommitSha() {
  sh "git rev-parse HEAD > .git/current-commit"
  return readFile(".git/current-commit").trim()
}

def updateGithubCommitStatus(build) {
  // 解决 https://issues.jenkins-ci.org/browse/JENKINS-38674 的问题
  repoUrl = getRepoURL()
  commitSha = getCommitSha()

  step([
    $class: 'GitHubCommitStatusSetter',
    reposSource: [$class: "ManuallyEnteredRepositorySource", url: repoUrl],
    commitShaSource: [$class: "ManuallyEnteredShaSource", sha: commitSha],
    errorHandlers: [[$class: 'ShallowAnyErrorHandler']],
    statusResultSource: [
      $class: 'ConditionalStatusResultSource',
      results: [
        [$class: 'BetterThanOrEqualBuildResult', result: 'SUCCESS', state: 'SUCCESS', message: build.description],
        [$class: 'BetterThanOrEqualBuildResult', result: 'FAILURE', state: 'FAILURE', message: build.description],
        [$class: 'AnyBuildResult', state: 'FAILURE', message: 'Loophole']
      ]
    ]
  ])
}

更新日志

GitHub 发布

开发

启动本地 Jenkins 实例：

mvn hpi:run

Jenkins 插件 Maven 目标

hpi:create  创建新插件的骨架。

hpi:hpi 构建 .hpi 文件

hpi:hpl 生成 .hpl 文件

hpi:run 使用当前插件项目运行 Jenkins

hpi:upload 将 hpi 文件发布到 java.net。在发布过程中使用。

如何安装

运行

mvn hpi:hpi

来创建插件的 .hpi 文件。

安装方法：

1. 将生成的 ./target/rdoc.hpi 文件复制到 $JENKINS_HOME/plugins 目录。别忘了之后重启 Jenkins。

2. 或者使用插件管理控制台（https://example.com:8080/pluginManager/advanced）上传 hpi 文件。你需要重启 Jenkins 才能在已安装插件列表中找到该插件。

插件发布

mvn release:prepare release:perform -Dusername=juretta -Dpassword=******