@kyanny's blog

My thoughts, my life. Views/opinions are my own.

Jenkins のジョブを外部からビルドするには API Token を利用する

Jenkins 1.594 にて確認。

Jenkins の認証ありの場合

「セキュリティを有効化 / Enable security」にチェックを入れている場合。

認証必須環境におけるJenkinsのスクリプトトリガーによるビルドの実行 - そんなこと覚えてない そして Authenticating scripted clients - Jenkins - Jenkins Wiki にあるように、Jenkins のログインユーザー固有の API Token を使って BASIC 認証し、 $JOB_URL/build に POST リクエストを送ればよい。

API Token はユーザー設定ページというものがあり、そこから取得できる。

f:id:a666666:20141219223605p:plain

ログインユーザーのユーザー名が kyanny で API Token が xxxxxxxx だとすると、

$ curl -X POST -u kyanny:xxxxxxxx http://jenkins.example.com/JOB_NAME/build

というリクエストを送ればよい。

(上記は例なので HTTP で POST リクエストを送っているが、 API Token が盗聴される可能性があるので、 HTTPS 接続できるようにしたほうがよい)

Jenkins の認証なしの場合

「セキュリティを有効化 / Enable security」のチェックを外している場合。

ただ単に $JOB_URL/build に POST リクエストを送ればよい。

$ curl -X POST http://jenkins.example.com/JOB_NAME/build
ProTip: "Trigger builds remotely" は設定不要

Enable security をオンにしている場合、ジョブの設定ページの「ビルド・トリガ / Build Triggers」セクションに「リモートからビルド (例: スクリプトから) / Trigger builds remotely (e.g., from scripts)」という項目が表示される(Enable security オフだとこの項目は表示されないらしい

この機能を使ってジョブ固有の認証トークン文字列を設定したらビルド URL へ POST するときに ?token=TOKEN_STRING パラメータが必須...ではなかった。 API Token による BASIC 認証のみでビルドを開始できる。 Trigger builds remotely がオフでも、オンで認証トークンが空文字列でも、任意の文字列を保存しても、いずれの場合も ?token= パラメータを送らずにビルド可能。

$JOB_URL/api/ の Perform a build セクションの最後に、

If security is enabled, the recommended method is to provide the username/password of an account with build permission in the request. Tools such as curl and wget have parameters to specify these credentials. Another alternative (but deprecated) is to configure the 'Trigger builds remotely' section in the job configuration. Then building or polling can be triggered by including a parameter called token in the request.

とあるので、このトークンを使った認証機能のことは忘れてよさそう。Authenticating scripted clients - Jenkins - Jenkins Wiki にある wget を使った例ではいまだに token パラメータ必須のように見えるが、どこかのタイミングで Jenkins の仕様変更があってドキュメントが更新されていないか、単にバグなのかもしれない。