Jenkins workflow plugin FAQ集


Jenkins workflow pluginで色々と試してみたので分かったことをFAQ集として残しておきます。今後もうちょっと使いこなして追加するかもしれません。
※執筆時のWorkflow pluginの最新バージョンは1.8です。

## Wokflow Pluginが対応しているJenkins Pluginは？
[COMPATIBILITY](https://github.com/jenkinsci/workflow-plugin/blob/master/COMPATIBILITY.md)にまとめられているのでこちらを参照すると良い。

## 使えるDSLが良く分からない
[TUTORIAL](https://github.com/jenkinsci/workflow-plugin/blob/master/TUTORIAL.md)をまず読もう。ここで代表的なDSLを学ぶことができるはず。
後は個別のドキュメントも参照しよう。

* [builder, post-build actions](https://github.com/jenkinsci/workflow-plugin/blob/master/basic-steps/CORE-STEPS.md)
* [SCM](https://github.com/jenkinsci/workflow-plugin/blob/master/scm-step/README.md)

あとは困ったらソースを読む。 `～Step`というクラスでDSLが実装されているのでこれらを読むとよい。例えば、`echo`ステップの[ソースはこれ](https://github.com/jenkinsci/workflow-plugin/blob/master/basic-steps/src/main/java/org/jenkinsci/plugins/workflow/steps/EchoStep.java)だが、[引数はString型](https://github.com/jenkinsci/workflow-plugin/blob/master/basic-steps/src/main/java/org/jenkinsci/plugins/workflow/steps/EchoStep.java#L44-L47)しか受け取れない仕様であることが分かる。`@DataBoundConstructor`, `@DataBoundSetter`が付与されているところが引数で渡せる情報。

## ユーザからの入力を受け付けて処理させたい
[`input`ステップ](https://github.com/jenkinsci/workflow-plugin/blob/master/TUTORIAL.md#pausing-flyweight-vs-heavyweight-executors)を使うと、処理を一時停止させユーザからの入力待ちにさせることができる。
また、ユーザ操作からパラメータを受け取ることもでき、そのパラメータをハンドリングをして後続の処理を決定することもできる。
パラメータを受け取るには、`parameters`を設定する。ここには、[ParameterDefinitionのサブクラス](http://javadoc.jenkins-ci.org/hudson/model/ParameterDefinition.html)が指定できるので、文字列入力だけでなく、プルダウンによる選択も可能となっている。
また、下記のように`input step`の戻り値で設定された値が取れる。

```groovy
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`プロパティで参照できる。

```groovy
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}をデプロイします..."
```
実際の入力受付画面はこのようになる。
![workflow-inputStep.png](https://qiita-image-store.s3.amazonaws.com/0/35233/624d7528-1507-5ce1-ff36-a16e2f33ce44.png)

## inputステップを自動的にキャンセルさせたい
`input`ステップを使用したWorkflowジョブをどんどん起動すると、ユーザ入力待ちでジョブが滞留することになる。[JENKINS-27039: Option for input or stage step to cancel older executions](https://issues.jenkins-ci.org/browse/JENKINS-27039)でキャンセルのFeature Requestがあがっているが、まだ実装されていない。
現時点だと、[JENKINS-27039](https://issues.jenkins-ci.org/browse/JENKINS-27039)に書かれているように下記のように`timeout`ステップと組み合わせると一応実現できる。

```groovy
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](https://github.com/jenkinsci/workflow-plugin/blob/master/basic-steps/CORE-STEPS.md#interacting-with-build-status)に書かれている`currentBuild`を利用することで実現できる。

```groovy
// 実際はビルドのパラメータ化などで受け取る
def version = '1.1'

currentBuild.description = "v${version}-${env.BUILD_NUMBER}をDEV環境にデプロイしました"
```
ビルド履歴には以下のように表示される。
![workflow-buildDescription.png](https://qiita-image-store.s3.amazonaws.com/0/35233/b7c0ffa0-717b-9bf2-9ede-b3e73e8bbc1b.png)

## 任意のタイミングでビルドを強制エラーとして終了させたい
`error`ステップを使う。これで終了させるとWorkflowジョブはエラーとして記録される。
```groovy
error 'デプロイ環境に接続できないため中断します'
```
なお、エラーとして記録させずに停止は現状できない模様。[JENKINS-27092: create a step to abort the build with a NOT_BUILT status](https://issues.jenkins-ci.org/browse/JENKINS-27092)でFeature Requestはあがっている。

## パラメータを渡して外部のジョブを呼び出したい
`build`ステップを使ってWorkflowジョブとは別のジョブをキックすることができるが、その際に任意のパラメータを渡すこともできる。
例えば、`DEPLOY-DEV`というDEV環境にデプロイ処理を行うだけのフリースタイルジョブが定義されているとする。このジョブは`componentName`、`packageName`変数を利用するように定義されている場合、下記のように`parameters`でそれらの値を渡す。

```groovy
build job: 'DEPLOY-DEV', parameters: [
    [$class: 'StringParameterValue', name: 'componentName', value: 'myApp'],
    [$class: 'StringParameterValue', name: 'packageName', value: "myApp-v${version}-${env.BUILD_NUMBER}"]
]
```