2015年03月02日

#JenkinsCI CLI(jenkins-cli.jar)でジョブをbuildする

このエントリーをはてなブックマークに追加

CLI(jenkins-cli.jar)を扱った情報が少ない

今回はCLI(jenkins-cli.jar)を使ってジョブをbuildしてみる。軽く検索した限りでは欲しい日本語情報が見つからなかったので、探していた人にとっての有用情報になってくれたなら、幸いである。

CLI(jenkins-cli.jar)セットアップ手順は、以下のエントリ。

検証環境

  • CentOS release 6.6
  • jenkins-1.599-1.1.noarch
  • java-1.6.0-openjdk-1.6.0.0-11.1.13.4.el6.x86_64

CLI(jenkins-cli.jar)でbuildする方法

http://127.0.0.1:8080/cli/command/buildより:

java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ build JOB [-c] [-f] [-p] [-r N] [-s] [-v] [-w]
Starts a build, and optionally waits for a completion.
Aside from general scripting use, this command can be
used to invoke another job from within a build of one job.
With the -s option, this command changes the exit code based on
the outcome of the build (exit code 0 indicates a success)
and interrupting the command will interrupt the job.
With the -f option, this command changes the exit code based on
the outcome of the build (exit code 0 indicates a success)
however, unlike -s, interrupting the command will not interrupt
the job (exit code 125 indicates the command was interrupted)
With the -c option, a build will only run if there has been
an SCM change
 JOB : Name of the job to build
 -c  : Check for SCM changes before starting the build, and if there's no
       change, exit without doing a build
 -f  : Follow the build progress. Like -s only interrupts are not passed
       through to the build.
 -p  : Specify the build parameters in the key=value format.
 -s  : Wait until the completion/abortion of the command. Interrupts are passed
       through to the build.
 -v  : Prints out the console output of the build. Use with -s
 -w  : Wait until the start of the command

オプション指定方法を除くと、基本は

java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ build JOB

である事が分かる。

基本編

ここからは基本的なbuildを順に試して行く。

基本1: オプションなし/ジョブ登録(予約)

ジョブ登録(予約)である。何故、予約なのか?それは、CLIがジョブの結果を待たないからだ。これはWebUIからbuildするのと同じである。WebUIの操作に慣れている場合は、いつもの操作であるはずだ。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing

ジョブ登録が成功した場合は何も表示されず、凄くUNIXらしい振る舞いをする。終了コードもUNIXらしい振る舞いをする。成功時の$?0で、失敗時はnon 0だ。 ‘

基本2: -w/ジョブが開始するまで待つ

ジョブ予約するだけでなく、ジョブが起動するまでは待ちたい場合もある。そんな時は、-wオプションの出番だ。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -w
Started testing #39

Started <JOB> #<build-ID>が表示され、コマンドが正常終了する。

基本3: -s/ジョブの実行結果を待つ

ジョブが予約・起動するのを確認するだけでなく、ジョブの結果が出るまで待ちたい場合もある。そんな時は、-sオプションの出番だ。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -s
Started testing #40
Completed testing #40 : SUCCESS

先程の-wオプションによる実行結果に加え、Completed <JOB> #<build-ID>: <build>成否が表示され、コマンドが正常終了する。

基本4: -s -v/ジョブの実行結果を待ち、buildのconsoleログを表示

-sオプションで分かるのは、buildの成否までだ。しかし、buildのconsoleログが表示されない。デバッグ時やJOB登録直後の調整時にはconsoleログを表示したくなる。そんな時は、-vオプションの出番だ。-vは単体では無く-sと一緒に使う事が期待されている。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -s -v
Started testing #41
Started from command line by hansode
Building remotely on ct103.ci03.dh (centos-6.4 vz.vm vz.kemumaki fpmbox rbenv) in workspace /var/lib/jenkins/workspace/testing
 > git rev-parse --is-inside-work-tree # timeout=10
Fetching changes from the remote Git repository
 > git config remote.origin.url https://github.com/axsh/wakame-vdc.git # timeout=10
Fetching upstream changes from https://github.com/axsh/wakame-vdc.git
 > git --version # timeout=10
 > git fetch --tags --progress https://github.com/axsh/wakame-vdc.git +refs/heads/*:refs/remotes/origin/*
 > git rev-parse origin/master^{commit} # timeout=10
Checking out Revision ed54f8de7e72f8902700fff011a26398790bf710 (origin/master)
 > git config core.sparsecheckout # timeout=10
 > git checkout -f ed54f8de7e72f8902700fff011a26398790bf710
 > git rev-list ed54f8de7e72f8902700fff011a26398790bf710 # timeout=10
 > git tag -a -f -m Jenkins Build #41 jenkins-testing-41 # timeout=10
[testing] $ /bin/bash -xe /tmp/hudson9218072417606499332.sh
+ date
Sun Mar  1 22:53:02 JST 2015
Finished: SUCCESS
Completed testing #41 : SUCCESS

-sオプション単体指定時よりも出力結果が多い事は一目瞭然だ。

基本編のまとめ
  1. オプションなし: ジョブ登録のみ
  2. -w: ジョブ登録、そしてジョブ起動するまで待つ
  3. -s: ジョブ登録・ジョブ起動、そしてジョブ成否が出るまで待つ
  4. -s -v: ジョブ成否が出るまで待ち、更にconsoleを出力

応用編

次に応用編を試して行く。

応用1: -p KEY=VALUE/パラメタつきbuild

ジョブの中には、パラメタ化してあるものもあるはずだ。常にデフォルト値で良い訳が無い。そんな時は-p KEY=VALUEの出番だ。以下の例ではビルド結果表示を分かりやすくするために-wを指定している。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -w -p GIT_BRANCH=ci-fail
Started testing #80

もしも存在しないパラメタを指定すると、その旨を表示して教えてくれる。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -w -p GIT_BRANCH2=ci-fail
'GIT_BRANCH2' is not a valid parameter. Did you mean GIT_BRANCH?

似たパラメタが存在する場合は、なんと、似たパラメタ名を教えてくれている!

応用2: -c/ソースコードに変更がある場合のみbuild

build命令を受け取ると、Jenkinsはソースコードに変更があろうともなかろうともbuildする。時には変更がある場合のみbuildした場合もある。そんな時は、-cオプションの出番だ。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -c
Using strategy: Default
[poll] Last Built Revision: Revision e6cc9351e46bc8d062d5b7d27d18cba366e138bf (origin/ci-fail)
 > git --version # timeout=10
 > git ls-remote -h https://github.com/axsh/wakame-vdc.git # timeout=10
[poll] Latest remote head revision on origin/ci-fail is: e6cc9351e46bc8d062d5b7d27d18cba366e138bf - already built by 80

この結果では、already built by 80と表示され、buildされない事が分かる。もしも疑わしい場合は再度-cオプション指定で実行してみると良い。何度実行しても同じbuild番号が出力されるので、buildされてない事を確認出来る。

応用3: -f/ジョブの中断を無視?

-fオプション指定で実行した場合、コマンドを中断した場合でも、ジョブを中断しないように制御出来るらしい。それに対し、-sオプションの場合はコマンドを中断すると、それに応じてジョブを中断するようである。

ここで曖昧な表現になっているのは、-f-sの違いを明確に確認出来なかった為である。今後もしも明確な差を得られた場合は、この内容を加筆・修正する。

応用編のまとめ
  1. -p KEY=VALUE: パラメタ付きbuild
  2. -c: 変化がある時のみbuild
  3. -f: ジョブ中断を無視?

参考文献

補足:終了コードの扱い

コマンド成否は、コマンドの終了コードを使って判断可能である。その為、パイプと組み合せたコマンドライン操作やシェルスクリプトとの相性は良い。

ジョブが正しく失敗する場合

意図的にジョブが失敗するように設定を変更してみる。確認したいのは、出力結果と終了コードだ。実行し、結果を確認してみる。

$ java -jar jenkins-cli.jar -s http://127.0.0.1:8080/ -i /path/to/id_rsa build testing -s -v
Started testing #94
Started from command line by hansode
Building remotely on ct103.ci03.dh (centos-6.4 vz.vm vz.kemumaki fpmbox rbenv) in workspace /var/lib/jenkins/workspace/testing
 > git rev-parse --is-inside-work-tree # timeout=10
Fetching changes from the remote Git repository
 > git config remote.origin.url https://github.com/axsh/wakame-vdc.git # timeout=10
Fetching upstream changes from https://github.com/axsh/wakame-vdc.git
 > git --version # timeout=10
 > git fetch --tags --progress https://github.com/axsh/wakame-vdc.git +refs/heads/*:refs/remotes/origin/*
 > git rev-parse origin/master^{commit} # timeout=10
Checking out Revision ed54f8de7e72f8902700fff011a26398790bf710 (origin/master)
 > git config core.sparsecheckout # timeout=10
 > git checkout -f ed54f8de7e72f8902700fff011a26398790bf710
 > git rev-list ed54f8de7e72f8902700fff011a26398790bf710 # timeout=10
 > git tag -a -f -m Jenkins Build #94 jenkins-testing-94 # timeout=10
[testing] $ /bin/bash /tmp/hudson2042532681956823107.sh
+ hoge
/tmp/hudson2042532681956823107.sh: line 5: hoge: command not found
Build step 'Execute shell' marked build as failure
Finished: FAILURE
Completed testing #94 : FAILURE

ジョブは完了し、結果はFAILURE

$ echo $?
2

そして終了コードは2non 0だ。

終了コードのまとめ
  1. 成功時: 0
  2. 失敗時: non 0

失敗時の終了コードは、失敗内容によって変化する。

あとがき

CLI(jenkins-cli.jar)を使ってみて分かったのは、curlコマンドなどによるRemote API経由操作よりも、細かな操作が可能である事だ。認証プラグインとの組み合わせ課題をきっかけに検証を始めた訳だが、今の所は使ってみて良かったと思える。もしかしたら、近いうちに他のコマンドも試してみるかも知れない。




編集
@hansode at 10:30│Comments(0)TrackBack(0)Jenkins 

トラックバックURL

コメントする

このブログにコメントするにはログインが必要です。