JenkinsとGitHubのWebhook連携の整理

2017.03.03
インフラ

1. Jenkins と GitHub を連携させる Webhook について
2. 今回 Webhook で実現したい Jenkins ジョブ
3. Jenkins と GitHub を Webhook で連携させる様々な方法
4. Jenkins 標準 Webhook
5. Git Plugin
6. GitHub Plugin
7. まとめ
8. 参考文献

Jenkins と GitHub を連携させる Webhook について

GitHub と Jenkins を連携させる機能のひとつに「Webhook」と呼ばれるものがあります。この Webhook をつかうことで、 GitHub 上で管理しているリポジトリにブランチを push したときや、新たに Pull Request を作成した時などに Jenkins のジョブを走らせるといったことができます。

しかしながら、 Jenkins や Jenkins の複数のプラグインが Webhook の機能を提供しており、どの機能がどのサービスを提供しているのかがわかりづらくなっているのが現状です。そこでこのエントリーでは、それぞれの機能でどのような特徴があり、どういった設定が必要なのかを、実際に設定を行いながら整理したいと思います。

なお使用している Jenkins のバージョンはこの記事執筆時点での Jenkins の最新バージョンの安定バージョン 2.32.3 LTS です(各プラグインのバージョンについては項目ごとに記述)。

今回 Webhook で実現したい Jenkins ジョブ

GitHub 上で管理している Git リポジトリの master ブランチへ push したときに特定の Jenkins ジョブのビルドを実行する
- master 以外のブランチの push イベントではビルドを実行しないようにできるのが理想です
ビルドの実行内容はリポジトリ内に含まれる README.md を表示するだけのものにします

#!/bin/sh -xe
cat README.md

Jenkins と GitHub を Webhook で連携させる様々な方法

Jenkins を GitHub と Webhook によって連携させる方法は、主に以下の3つがあります。

Jenkins 標準 Webhook
- Jenkins の標準機能として提供されている「リモートからビルド」の設定
Git Plugin
- Jenkins のビルドの際に git リポジトリをクローンして実行できる機能を提供できるプラグイン
GitHub Plugin
- GitHub からの push イベントを受け取るプラグイン
- Jenkins から GitHub に Webhook の自動登録ができる

それぞれの手段とプラグインについての特性をまとめると以下のようになります。

方法	設定の容易さ	汎用性	セキュリティ
Jenkins 標準 Webhook	△	◎	○
Jenkins 標準 Webhook	適切に権限などを設定できればセキュリティは高い
Git Plugin	○	△	×
Git Plugin	push イベントを受け取るのは容易
GitHub Plugin	◎	△	×
GitHub Plugin	GitHub 側の Webhook 登録も自動でできる(設定が必要)

次にプラグインごとの設定についてなど手順を追って詳しく見ていきましょう。

Jenkins 標準 Webhook

Jenkins のビルドトリガーの1つに、「リモートからビルド」という設定項目があります。これは Jenkins に標準の機能として提供されているもので、特にプラグインなどを導入しなくてもこの項目を有効にすれば Webhook の機能を利用することができます。

では Jenkins 標準の Webhook を使って実際に設定してみましょう。

Jenkins 側の設定

▷ ビルド・トリガの設定

ジョブ設定の「ビルド・トリガ」の中から「リモートからビルド (例: スクリプトから)」を有効にすると、 Jenkins 側に http://[JENKINS_URL]/job/[JOB_NAME]/build 、 http://[JENKINS_URL]/job/[JOB_NAME]/buildWithParameters というエンドポイントができ、ここに Webhook を仕掛けることでジョブを実行させることができます。

/buildWithParameters を使うと GitHub から送られてくるイベントの詳細(payload)を Jenkins 側で受け取ることができます(payload については後述)。この URL を GitHub 側にセットする場合は、 Jenkins のジョブ設定にある「ビルドのパラメーター化」の項目に「payload」という名前の「文字列」項目をしておく必要があります(MUST)。このパラメーターを使う必要ないジョブの場合は /build を使うとよいでしょう。

ポイント

認証トークンは空欄でも設定でき、 Jenkins のセキュリティ機能を有効化している(ビルドの際にログインが必須になっている)場合、 API Token を使ったBasic認証が必須になるのでそちらで認証を一任したほうがいいかもしれません
ここで入力する「認証トークン」とは、後述する GitHub Webhook 設定画面にある「Secret」の設定とは無関係です

▷ ソースコード管理

Git リポジトリのクローンには Git Plugin が必要で、有効になっていれば Git という設定項目があるはずなので、「リポジトリURL」欄に Git の remote アドレスを入力します。このとき「ビルドするブランチ」も指定できるので、「*/master」などを設定すれば master ブランチを pull してくることができます。

GitHub 側の設定

続いて GitHub で Webhook の設定を行います。リポジトリのページから「Settings」>「Webhooks」>「Add Webhook」から追加することができます。

なお GitHub では Webhook の設定を行えるのはリポジトリの管理者(Admin)のみです。もしあなたがそのリポジトリの管理者でない場合などは Settings のリンクがないかもしれません。

▷ Jenkins にアクセスするための API Token を取得する

Jenkins のセキュリティ機能が有効になっている場合、ビルドを実行するには「ユーザーID」と「API Token」が必要になります。 API Token とはログイン時に用いる「パスワード」ではなく、アカウントごとに発行される32文字のランダムな英数字列です。

Jenkins の管理画面から、「Jenkinsの管理」>「ユーザーの管理」>「(API Token を取得したいユーザーID)」>「設定」>「APIトークンの表示」で取得することができます。

▷ 設定項目

今回の設定する項目は以下のとおりです。

Payload URL
- http://[USER_ID]:[API_TOKEN]@[JENKINS_HOST]/job/[JOB_NAME]/[build|buildWithParameters]?token=[TOKEN_NAME]
  - 例) http://admin:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@jenkins.example.com/job/webhook_job/buildWithParameters?token=hogehoge
Content type
- application/x-www-form-urlencoded
Secret
- (空欄)
  - Jenkins ジョブ設定で入力した認証トークンの項目と連動していません。トークンを設定した場合は Payload URL の中にパラメーターとして入力する必要があります
Which events would you like to trigger this webhook?
- Just the push event.
  - 今回目標としているジョブを実現するには push イベントだけ受け取れば良いので、今回は push イベントだけを通知してもらう設定にします
  - push 以外のイベントが必要な場合や、 Jenkins 側で push 以外のイベントを受け取って実行するジョブの内容を変更したりする場合などは、「Send me everything(送れる限り全てのイベントが送信されるようになる)」や、「Let me select individual events.(送ってくるイベントの種類を選択することができる)」などで設定しても良いと思います。

動かしてみる

おそらく上記の設定が正しくできていれば GitHub に push するとビルドが実行されて、ビルド結果をみると README.md が表示されるようになっているはずです。

しかしながらここで1つ問題が発生します。ここまでの設定だけでは master ブランチ以外のブランチを push してもビルドが実行されてしまいます。今回のような処理が軽いビルドであれば大した問題ではありませんが、もし成果物のコンパイルやデプロイなどを行うジョブの場合は、今のようにブランチが push される度に動いたらたまったものではありません。

この問題の解決は GitHub の設定だけではできません。 GitHub は push イベントと Webhook を連動させることはできますが、「○○ブランチが push された時だけ hook する」など、イベントの内容による切り分けが行えないので、細かい部分については Webhook を受け取る Jenkins 側でうまく制御する必要があります。

master ブランチが push された時だけ実行されるようにするには

master ブランチ以外が push されたときにビルドを実行しないようにするには、ジョブの設定時に紹介した payload というパラメーターが役に立ちます。 payload は GitHub が Webhook で設定された URL にアクセスする際に「どういったイベントの発生によって叩かれたのか」であったり、どのブランチで起きたイベントなのかなど、原因となるイベントの詳細情報が入っているパラメーターです。

今回はこの payload という値と、 Jenkins プラグインの Conditional BuildStep Plugin を使って master ブランチが push された際にだけビルドを行うように制御したいと思います。

Conditional BuildStep Plugin が入っていれば、ビルド手順の追加の項目の中に「Conditional step (single)」というものがあると思うので、これを追加して以下のように設定します。

項目	内容
Run?	Regular expression match
Expression	`."ref":"refs\/heads\/master".`
Label	`${ENV,var="payload"}`
On evaluation failure	Don’t run

これを設定を追加したことで master ブランチ以外のビルドを push したときにジョブの実行はされますが、ビルドの処理内容である「README.md の表示」までは行われないようになっているはずではないでしょうか。

メリット

この機能をつかって GitHub と連携させることのメリットは、 payload パラメーターを取得することができることです。今回は payload をつかって「master ブランチが push されたときのみ」という条件で処理を実行するかどうかを判断させましたが、これ以外にもいろいろな情報が payload には入っているので、もっと複雑な条件でもビルドの実行を判断させることができます。

デメリット

Jenkins の認証情報などセキュリティ情報を Webhook に設定する URL の中に含んで設定する必要があるのでセキュリティ的にはあまり良いとは言えないかもしれません。特に API Token などが流出した場合、そのユーザーの権限が許す限り Jenkins の設定内容を変更されてしまう可能性があります。

またこの Webhook の URL は1つのジョブにつき1ずつ発行されるので、1つのリポジトリのイベントから色々なジョブを実行したい場合などは、 Jenkins 側に受け口となるジョブを1つ用意するか、 GitHub 側に複数の Webhook を仕掛ける必要があります。

またメリットにあった payload の値によってジョブの実行内容を変えるといった処理は一見便利ですが、一方で設定が煩雑になりがちです。あなた以外の人がジョブの設定を行うことがある場合、あまり優しいとはいえないかもしれません。

Git Plugin

Jenkins の Git Plugin は「Jenkins のジョブ実行前に Git リポジトリをクローンしてくれる」という機能がメインですが、それだけではなく、実は Webhook の機能もあります。さらに GitHub 側もこのプラグインを使った Webhook Service の設定に対応しており、 Jenkins 標準 Webhook であったような煩雑な認証の設定などが必要なく、比較的簡単に導入することができます。

ブランチの push によってビルドを実行したい場合は、おそらくいちばん手頃な方法です。