Jenkinsfile入門

このページは、” Getting Started with the Jenkinsfile“の和訳です（原典2016/7/2時点）。Getting Started with the Jenkinsfileは、 CC BY-SA 4.0で提供されています。

読者と目的

このドキュメントはpipleline機能のパワーを活用したいと思っているJenkinsユーザー向けのものです。Pipeline入門の”Hello World”の例で学んだことから一歩進めて、このドキュメントではJenkinsfileの使い方を説明し、あるリポジトリの中身のシンプルなチェックアウトとビルドを実行します。

Jenkinsfileを作成する

Jenkinsfileはpipeline（や他の）スクリプトのコンテナであり、Jenkinsに望む用途のジョブを実行するために必要となる一つひとつのステップを詳細化します。Jenkinsfileは好みのGroovyエディタ、またはJenkinsインスタンスのWebインターフェース上の設定ページを通じて作成します。

JenkinsfileのコーディングにGroovyエディタを使えば複雑なシングル／マルチブランチpipelineをより柔軟に構築できますが、やりたいことに関して基礎的なJenkinsfileの内容に慣れていれば、エディタを使うかJenkinsインターフェースを使うかは問題になりません。

JenkinsインスタンスまたはGroovyエディタを開く
編集したいディレクトリに移動する（プロジェクトのルートディレクトリに置くこと）
Jenkinの標準構文で記述する
ファイルを保存する

後述の例はMavenプロジェクト向けにビルドとテストを行う基礎的なJenkinsfileを示したものです。nodeは後続のブロック内のタスクをスケジュールするステップで、引数で指定されるラベルにマッチするマシン（通常はエージェント）で実行されます（この例では”linux”と呼ばれるnode）。中カッコ（{と}）間のコードがnodeステップの本体です。checkout scmコマンドは、このJenkinsfileがマルチブランチサポートを視野に入れていることを示しています。

node ('linux'){
  stage 'Build and Test'
  env.PATH = "${tool 'Maven 3'}/bin:${env.PATH}"
  checkout scm
  sh 'mvn clean package'
 }

シングルブランチのコンテキストではcheckout scmを以下のような特定のリポジトリを呼び出すようなソースコードチェックアウトのステップに置き換えられます。

git url: "https://github.com/my-organization/simple-maven-project-with-tests.git"

プルリクエストを実行

プルリクエストは、単体の変更や変更のセットの対象となるJenkinsリポジトリの保守をしている責任者の人物に、そのリポジトリに関連づけられているメインブランチにマージして欲しいと通知するものです。個別の変更は”commit”と呼ばれます。

プルリクエストはコマンドライン、またはソースコード管理システム用のインターフェースにある適切なラベルのボタン（典型的には”Pull”や”プルリクエストを作成”）を選択することで実行できます。

Organization Folderに含まれているかモニタされているリポジトリへのプルリクエストはマルチブランチのpipelineビルドの自動実行に利用できます。

Organization Folderを利用する

Organization Folderを用いることで、Jenkinsはその中にある新規のリポジトリであれば自動で検出してリソースとしてインクルードできるようになります。

リポジトリを新規作成（新規プロジェクトのケースの想定例として）する際、そのリポジトリにはJenkinsfileがあります。１つ以上のOrganization Folderを設定しておくと、Jenkinsは自動的にOrganization Folder内のあらゆるリポジトリを検出し、リポジトリの内容をデフォルトまたは設定にもとづく時間間隔にそってスキャンし、その際発見したマルチブランチPipelineプロジェクトを作成します。Organization Folderは「親」として機能し、その中のあらゆる項目はその「子」として扱われます。

Organization Folderは新規リポジトリのためのプロジェクトを手動作成しなくてはならない必要性を緩和するものです。Organization Folderを使うと、Jenkinsはレポジトリを階層構造で認識し、各リポジトリ（Organization Folderの１つ）はブランチやプルリクエストといった子要素を持つことも可能（オプション）です。

Organization Folderの作成手順：

Jenkinsをブラウザで開く
New Item→GitHub Organization または New Item→Bitbucket Team に移動
設定手順を実行。GutHub OrganizationやBitbucket Team名に対応するスキャン時の認証情報とオーナーを適切に指定していることを確認すること
求めるトリガー種別に対応するチェックボックスを選択してビルドトリガーをセットする。フォルダスキャンとそれに関連するpipelineビルドはコマンドスクリプトから実行したり定義した時間間隔で実行できる。また、プロジェクトpromotionやモニターしているDocker Hubのイメージの変更からもトリガーできる
不使用アイテムの自動削除するか保持するかを決める。設定インターフェースの”Orpahed Item Strategy”フィールドを通じて古いアイテムを何日間保存するか、またはいくつまで古いアイテムを保存するかを指定できる。これらのフィールドに何も入力していない場合、不使用アイテムはデフォルトで削除される。

Organization Folderの設定では、以下のオプションも指定できる

Repository name pattern：スキャンにどのリポジトリを含めるかを正規表現で指定
API endpoint：自前ホストしているGitHub Enterpriseを利用する場合のための別のAPIエンドポイント
Checkout credentials：コードをチェックアウト（clone）する際に利用する他の認証情報

マルチブランチPipelineプロジェクトとOrganization Folderは”computed folder”機能の例です。マルチブランチPipelineプロジェクトではプログラムにより的確なブランチのための子アイテムが作成されます。Organization Folderでは、プログラムはスキャンしたリポジトリのために個別のマルチブランチPipelineとして子アイテムを作成します。

Jenkinsインターフェースの”Folder Computation”セクションを選択してプログラム実行にかかった時間（秒単位）と結果（成功または失敗）を確認するか、Folder Computation Logにアクセスすることでその活動に関するより詳細な情報を得られます。

チェックアウトとビルドの基礎

チェックアウトとビルドコマンドの例は上記の紹介で用いたコード例に示しました。この例ではJenkinsがLinuxまたは何らかのUnixライクなOS上で動作していることを仮定しています。

もしJenkinsサーバーやエージェントがWindowsで動作しているのであれば、Bourneシェル（sh）またはBourne-Againシェル（bash）がソフトウェアビルドの起動のためのコマンド言語インタプリタに使われていない可能性があります。Windows環境では、shの部分でbatを、パス名のファイルセパレータとしてスラッシュではなくバックスラッシュ（\）を用います。