こんにちは！開発現場の自動化を進めていると、「GitHubのWebhookをトリガーにJenkinsを動かしたい」「別の自製システムから、パラメータを渡してビルドをサクッとキックしたい」といった壁にぶつかることがよくありますよね。
GUIをポチポチ操作するだけの自動化なんて、もう卒業です。今回は、JenkinsのWebAPIを完全に手なづけ、外部ツールから自由にジョブを操るための極意を伝授します。
これをマスターすれば、あなたのシステムとJenkinsがシームレスに連携し、毎日の開発作業が劇的に楽になりますよ。さあ、一緒に扉を開けましょう！
—
1. Jenkins WebAPIの役割と、なぜ「直接叩く」のか？
通常、Jenkinsを使うときはブラウザでログインし、ダッシュボードから「ビルド実行」ボタンを押しますよね。しかし、CI/CDの本質は「人間の手を介さないこと」です。
Jenkinsは、そのすべての機能を「REST API」として外部に公開しています。つまり、ブラウザでできることは、すべてプログラム（`curl`やPythonなど）から実行可能です。
- 外部システムとの連携: GitHubやSlack、社内ポータルから直接ビルドを呼ぶ
- 動的なパラメータ制御: その時々の条件（ブランチ名や環境変数）を外から注入する
- ステータスの監視: ビルドが成功したか失敗したかを外部アプリにリアルタイムで伝える
これらを可能にするのがJenkins WebAPIです。
—
2. 基礎セットアップ：APIを叩くための「3種の神器」
APIを叩く前に、Jenkins側で準備すべき設定が3つあります。ここをサボると認証エラーの沼にハマるので、しっかりと押さえましょう。
① APIトークンの発行（パスワードをそのまま使わない）
JenkinsのユーザーパスワードをAPIリクエストに含めるのはセキュリティ上、御法度です。必ず「APIトークン」を発行してください。
1. Jenkinsの右上にある自分のユーザー名をクリック。
2. 「設定 (Configure)」を開く。
3. 「API Token」セクションの「新しいトークンを追加 (Add new token)」をクリック。
4. 適当な名前（例: `external-api-token`）を入れて生成し、表示されたトークンを必ず控えておく（二度と表示されません）。
② 認証情報の準備
APIリクエストを送る際は、基本認証（Basic Authentication）を使います。
`ユーザー名:APIトークン` の文字列を Base64エンコード したものを使用するのが基本です。
③ CSRFプロテクション（crumb）の理解 ★最重要！
これが初心者が一番ハマる罠です。JenkinsはデフォルトでCSRF（クロスサイトリクエストフォージェリ）対策が有効になっています。
そのため、データを書き換えるリクエスト（ビルドのトリガーなど）を送る時は、事前に「Crumb（クラム）」と呼ばれるワンタイムトークンを取得し、ヘッダーに付与しなければ403エラーになります。
—
3. 実践！curlでジョブをトリガーする（HelloWorld）
それでは、実際にLinuxのターミナルから `curl` を使って、Jenkinsのジョブをリモートから実行してみましょう。
今回は `my-first-job` という名前のフリースタイル・プロジェクトまたはパイプラインジョブが存在すると仮定します。
ステップ1: CSRFクラムの取得
まずはチケット（Crumb）をもらいます。
変数定義
JENKINS_URL=”http://your-jenkins-server:8080″
USER=”your-username”
TOKEN=”your-api-token”
クラムの取得とヘッダー用変数の保存
CRUMB=$(curl -u “$USER:$TOKEN” –silent “$JENKINS_URL/crumbIssuer/api/json”)
CRUMB_FIELD=$(echo $CRUMB | jq -r ‘.crumbRequestField’)
CRUMB_VALUE=$(echo $CRUMB | jq -r ‘.crumb’)
echo “Crumb Field: $CRUMB_FIELD”
echo “Crumb Value: $CRUMB_VALUE”
(※ `jq` コマンドがない場合は、適宜インストールするか手動でパースしてください)
ステップ2: パラメータなしジョブのキック
クラムを使って、シンプルにビルドをトリガーします。
curl -X POST “$JENKINS_URL/job/my-first-job/build” \
-u “$USER:$TOKEN” \
-H “$CRUMB_FIELD: $CRUMB_VALUE”
ステータスコード `201 Created` が返ってきたら大成功です！Jenkinsの画面に戻ると、見事にビルドがキューに積まれているはずです。
—
4. Parameterized Build（パラメータ付きビルド）の高度な制御
現実の開発では、ただジョブを回すだけでなく、「どの環境（Staging/Production）にデプロイするか」「どのブランチをビルドするか」といった動的パラメータを渡したいですよね。
ジョブ側の設定
Jenkins側で「このビルドはパラメータ プロジェクトです」にチェックを入れ、例えば `DEPLOY_ENV` という文字列パラメータを定義しておきます。
APIからの動的パラメータ渡し
パラメータを渡して実行する場合は、`/build` ではなく `/buildWithParameters` エンドポイントを叩き、クエリパラメータとして値を渡します。
curl -X POST “$JENKINS_URL/job/deploy-job/buildWithParameters” \
-u “$USER:$TOKEN” \
-H “$CRUMB_FIELD: $CRUMB_VALUE” \
–data-urlencode “DEPLOY_ENV=staging” \
–data-urlencode “BRANCH=feature/login-fix”
これで、外部システムから自由自在に環境やブランチを指定してビルドを暴れさせることができます。
—
5. Pythonを使ったスマートなステータス監視とポーリング
「ビルドをトリガーしたはいいが、それが成功したか失敗したかを知りたい」
外部ツールから制御する場合、ビルドの完了を検知して次の処理（例えばSlack通知や次のテストスイートの実行）につなげたいケースがほとんどです。
ここでは、Pythonを使って「ビルドをトリガーし、完了するまでポーリング（定期確認）する」スクリプトのテンプレートを共有します。
import time
import requests
from requests.auth import HTTPBasicAuth
JENKINS_URL = “http://localhost:8080”
USER = “admin”
TOKEN = “your-api-token”
JOB_NAME = “my-first-job”
auth = HTTPBasicAuth(USER, TOKEN)
1. CSRF Crumbの取得
crumb_res = requests.get(f”{JENKINS_URL}/crumbIssuer/api/json”, auth=auth)
crumb_data = crumb_res.json()
headers = {
crumb_data[“crumbRequestField”]: crumb_data[“crumb”]
}
2. ビルドのトリガー (Queueに積む)
trigger_res = requests.post(
f”{JENKINS_URL}/job/{JOB_NAME}/build”,
auth=auth,
headers=headers
)
if trigger_res.status_code != 201:
print(f”Failed to trigger build: {trigger_res.status_code}”)
exit(1)
print(“Build triggered successfully. Looking for Queue ID…”)
キューの位置から実際のビルド番号(Queue Item)を特定するのは少しコツが要りますが、
簡単のため、最新のビルドが何番になるかを取得しにいきます。
time.sleep(3) # キューが処理されるのを少し待つ
3. 最新のビルド情報を取得して完了をポーリング
while True:
# ジョブの一般情報を取得
job_info = requests.get(f”{JENKINS_URL}/job/{JOB_NAME}/api/json”, auth=auth).json()
last_build = job_info.get(“lastBuilding”) # または lastBuild
# 簡易的に、直近のビルドのステータスを確認
build_number = job_info[“lastBuild”][“number”]
build_info = requests.get(f”{JENKINS_URL}/job/{JOB_NAME}/{build_number}/api/json”, auth=auth).json()
if build_info[“building”]:
print(f”Build #{build_number} is still running…”)
time.sleep(5) # 5秒ごとにポーリング
else:
result = build_info.get(“result”)
print(f”Build #{build_number} finished with result: {result}”)
break
このスクリプトをベースにすれば、CI/CDパイプラインの一部としてPythonやNode.jsからJenkinsを完全にコントロールできるようになります。
—
6. さらに先へ：Webhookを使ったスマートな通知
ポーリング（定期的な死活確認）はシンプルで確実ですが、サーバーに負荷がかかります。
もしJenkins側から外部アプリ（Slack、Discord、独自サーバーなど）へ結果を能動的に伝えたい場合は、Jenkinsのプラグインである 「Generic Webhook Trigger Plugin」 や 「Notification Plugin」 を使うのがベストプラクティスです。
パイプラインの最後（`post` ブロック）で `curl` を叩かせ、外部へJSONを飛ばす仕組みを作っておくと、アーキテクチャが非常に美しくなります。
pipeline {
agent any
stages {
stage(‘Build’) {
steps {
echo ‘Building…’
}
}
}
post {
success {
sh ‘curl -X POST -H “Content-Type: application/json” -d \'{“status”: “SUCCESS”}\’ https://my-external-api.com/webhook’
}
failure {
sh ‘curl -X POST -H “Content-Type: application/json” -d \'{“status”: “FAILURE”}\’ https://my-external-api.com/webhook’
}
}
}
—
まとめ
今回は、JenkinsのWebAPIを駆使して外部からジョブを制御する方法を解説しました。
- CSRFクランブ（Crumb） の取得がAPI書き込みのキモであること
- `/buildWithParameters` を使えば動的なパラメータを自在に渡せること
- Python等を使ったポーリングにより、ビルドのライフサイクルを完全にプログラマブルに管理できること
これらを理解すれば、Jenkinsは単なる「CIツール」から、あなたのシステム全体を裏で支える「最強の自動化エンジン」へと生まれ変わります。
ぜひ、今日の開発からさっそく試してみてください。あなたのエンジニアリングライフが、もっと快適でエキサイティングなものになりますように！