Jenkins 2.0について書く記事の4回目です。今回は、GitHub連携について書きます。
GitHub連携でやりたいこと
昨今の一般的なCIサービスでは、GitHub連携に求められることは以下になります。
- リポジトリにpushしたら自動でビルド開始される
- ビルド結果をcommit statusへ反映
ちなみに、commit statusとは↓のようなGitHub上でコミットの状態を可視化してくれるすばらしいものです。
1.0時代のGitHub連携
過去のJenkinsのフリースタイルジョブで上記のようなGitHub連携を実現しようと思うと、GitHub Pluginをインストールした上で次のような設定が必要でした。
- 「Jenkinsの管理」→「システムの設定」→「GitHub」→「GitHub Servers」で「Add GitHub Server」
- 事前にGitHub側で “repo:status” を許可したPersonal access tokenを作成しておく
- ↑のトークンをCredentialsに “Secret text” として追加して設定する
- 「新規ジョブ作成」→「フリースタイル・プロジェクトのビルド」でジョブ作成
- 「ソースコード管理」で「Git」を選択
- 「Repository URL」を入力
- 「Branches to build」を「**」とかにする
- 「ビルド・トリガ」を設定
- ネットワーク的にGitHubからJenkinsへのWebhookリクエストが届くなら「GitHub hook trigger for GITScm polling」をチェック
- 届かないなら「SCMをポーリング」をチェック
- ビルド手順に、「Set build status to “pending” on GitHub commit」を追加
- 「ビルド後の処理」で「Set GitHub Commit Status」を設定
- 「Status result」に「One of default messages and statuses」を設定
な、長い。。
さらに辛いのは、最初のシステム設定以外はジョブを新しく作成するごとに設定する必要があるということです。これでは誰でも気軽にGitHub連携したジョブを作成できるとは言い難く、一般的にJenkins職人と呼ばれる人が誕生してしまうのもしょうがないでしょう。
GitHub Organization Folder
現在のJenkinsでは、 GitHub Organization Folder を使うことによってGitHub連携が圧倒的に楽になります。Organization Folderは、Organization内にあるリポジトリをスキャンして、リポジトリのルートにJenkinsfileがあるリポジトリに対してMultibranch Pipelineジョブ(後述)を自動で作成してくれます。
GitHub Organization Folderは、2.0でデフォルトでインストールされるGitHub Branch Source Pluginによって提供される機能です。以前は、GitHub Organization Folder Pluginの機能として提供されていましたが、GitHub Branch Source Pluginに機能が移譲されました。
新規ジョブ作成画面で、以下のように「GitHub Organization」という選択肢が表示されるようになります。
- 事前にGitHub側で “repo:status” を許可したPersonal access tokenを作成しておく
- 「新規ジョブ作成」→「GitHub Organization」でGitHub Organization Folderを作成
- 「Owner」にGitHubのOrganization名かユーザーIDを指定
- 「Scan credentials」に「ユーザー名とパスワード」としてGitHubのユーザーIDとPersonal access tokenの組み合わせを追加して設定する
- ネットワーク的にGitHubからJenkinsへのWebhookリクエストが届かないなら、「Scan Organization Triggers」の間隔をポーリングしたい間隔に設定しておく
- 自動ビルドしたいリポジトリのルートにJenkinsfileを追加する
だいぶ簡単になりましたね。
重要なのは、GitHub Organization Folderは一度設定してしまえば、同じOrganization内のリポジトリで新規ジョブを作成するときはJenkinsfileを作成するだけでいいということです。これは、チーム開発をする上でJenkinsおじさんの必要性を大きく下げてくれます。
一点注意が必要なのは、現時点ではOwnerにOrganizationではなくユーザーIDを指定したときはWebhookの登録が自動でされないので手動で行う必要があります。
Multibranch Pipeline
Organization Folderで作成されるMultibranch Pipelineジョブについて説明します。
Multibranch Pipelineはリポジトリ内のすべてのブランチに対して、push時の自動ビルドやビルド結果のcommit statusへの反映といったことを行います。また、リポジトリ内のブランチごとにビルドを分類してくれます。要は、CircleCIとかTravisとかと同じですね。
Multibranch Pipelineジョブは、Organization Folder以外でも、個別のリポジトリに対しても作成できます。「新規ジョブの作成」から「Multibranch Pipeline」を選択することで作成可能です。
ただし、こちらの方法で作成すると現時点ではGitHub側へのWebhookの登録を行ってくれないようなので、手動で “http://(Jenkins URL)/github-webhook/” へWebhookを設定する必要があります。
GitHubのpersonal access tokenのscopeについて
Jenkinsのcredentialに設定するGitHubのpersonal access tokenですが、なにをするためにどのscopeが必要なのかわかりにくいので簡単にまとめておきます。
repo
: privateリポジトリにアクセスするために必要repo:status
: commit statusを変更するために必要admin:repo_hook
: RepositoryにWebhookを設定するために必要admin:org_hook
: OrganizationにWebhookを設定するために必要
まとめ
Jenkins 2.0では、GitHub Organization FolderのおかげでGitHub連携がとても楽になりました。ちなみに、BitBucketにも対応しているようです。
まだ最初の設定まわりでいくらかはまりどころもありそうに感じますが、一度設定すればそのOrganization内では再設定の必要がなくなるというのはとても嬉しいです。