Jenkins workflow plugin FAQ集 #Jenkins

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ジョブはエラーとして記録される。
groovy 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}"]
]