Jenkins workflow pluginで色々と試してみたので分かったことをFAQ集として残しておきます。今後もうちょっと使いこなして追加するかもしれません。
※執筆時のWorkflow pluginの最新バージョンは1.8です。
Wokflow Pluginが対応しているJenkins Pluginは？
COMPATIBILITYにまとめられているのでこちらを参照すると良い。
使えるDSLが良く分からない
TUTORIALをまず読もう。ここで代表的なDSLを学ぶことができるはず。
後は個別のドキュメントも参照しよう。
あとは困ったらソースを読む。 ～StepというクラスでDSLが実装されているのでこれらを読むとよい。例えば、echoステップのソースはこれだが、引数はString型しか受け取れない仕様であることが分かる。@DataBoundConstructor, @DataBoundSetterが付与されているところが引数で渡せる情報。
ユーザからの入力を受け付けて処理させたい
inputステップを使うと、処理を一時停止させユーザからの入力待ちにさせることができる。
また、ユーザ操作からパラメータを受け取ることもでき、そのパラメータをハンドリングをして後続の処理を決定することもできる。
パラメータを受け取るには、parametersを設定する。ここには、ParameterDefinitionのサブクラスが指定できるので、文字列入力だけでなく、プルダウンによる選択も可能となっている。
また、下記のようにinput stepの戻り値で設定された値が取れる。
def v = input message: 'どの環境にデプロイしますか?',
ok: 'デプロイする',
parameters: [
[$class: 'ChoiceParameterDefinition',
choices: """\
DEV
STG01
STG02\
""",
description: 'デプロイ先の環境',
name: 'targetEnv']
]
if (v == null) {
error '選択してください'
}
echo "${v}にデプロイします..."
また、inputステップのparametersで複数のParameterDefinitionを設定している場合は、各パラメータのnameプロパティで参照できる。
def v = input message: 'どの環境にデプロイしますか?',
ok: 'デプロイする',
parameters: [
[$class: 'ChoiceParameterDefinition',
choices: """\
DEV
STG01
STG02\
""",
description: 'デプロイ先の環境',
name: 'targetEnv'],
[$class: 'StringParameterDefinition',
defaultValue: "tag-${env.BUILD_NUMBER}",
description: 'タグ名',
name: 'tagName']
]
if (v == null) {
error '選択してください'
}
echo "${v.targetEnv}に${v.tagName}をデプロイします..."
実際の入力受付画面はこのようになる。
inputステップを自動的にキャンセルさせたい
inputステップを使用したWorkflowジョブをどんどん起動すると、ユーザ入力待ちでジョブが滞留することになる。JENKINS-27039: Option for input or stage step to cancel older executionsでキャンセルのFeature Requestがあがっているが、まだ実装されていない。
現時点だと、JENKINS-27039に書かれているように下記のようにtimeoutステップと組み合わせると一応実現できる。
def x
try {
timeout(1) { // 1 minutes
try {
input 'Look good?'
} catch (InterruptedException _x) {
x = _x // rejected
}
}
} catch (InterruptedException _) {
// timeout, proceed
}
if (x != null) {
throw x
}
ビルドの説明に任意の値を設定するには？
Jenkinsではビルドの説明に任意の文字列を設定することでき、その内容はビルド履歴にも表示されるようになる。ちょっとした情報(例えば、Workflowジョブの実行結果として、v1.1をDEV環境にデプロイ といった内容など)を出力できたりすると便利。
これはInteracting with build statusに書かれているcurrentBuildを利用することで実現できる。
// 実際はビルドのパラメータ化などで受け取る
def version = '1.1'
currentBuild.description = "v${version}-${env.BUILD_NUMBER}をDEV環境にデプロイしました"
ビルド履歴には以下のように表示される。
任意のタイミングでビルドを強制エラーとして終了させたい
errorステップを使う。これで終了させるとWorkflowジョブはエラーとして記録される。
error 'デプロイ環境に接続できないため中断します'
なお、エラーとして記録させずに停止は現状できない模様。JENKINS-27092: create a step to abort the build with a NOT_BUILT statusでFeature Requestはあがっている。
パラメータを渡して外部のジョブを呼び出したい
buildステップを使ってWorkflowジョブとは別のジョブをキックすることができるが、その際に任意のパラメータを渡すこともできる。
例えば、DEPLOY-DEVというDEV環境にデプロイ処理を行うだけのフリースタイルジョブが定義されているとする。このジョブはcomponentName、packageName変数を利用するように定義されている場合、下記のようにparametersでそれらの値を渡す。
build job: 'DEPLOY-DEV', parameters: [
[$class: 'StringParameterValue', name: 'componentName', value: 'myApp'],
[$class: 'StringParameterValue', name: 'packageName', value: "myApp-v${version}-${env.BUILD_NUMBER}"]
]