Jenkins Use

Jenkins Use

Python スクリプトから Jenkins REST API を呼び出してビルド操作と状態監視を行う。

「設定して」リクエスト時の対応

ユーザーから「Jenkins を設定して」「接続情報を設定して」などのリクエストを受けたら以下を実行する:

1. 必要情報の確認: URL・ユーザー名・トークン・ラベルが指定されているか確認する。ない場合はユーザーに確認するか対話プロンプトを使う。
2. configure の実行: 必要情報が提示されている場合はオプション付きで、なければ対話形式で実行する。

# URL ・ユーザー名・トークンが分かっている場合
python {skill_home}/jenkins-use/scripts/jenkins_client.py --label default configure \
  --url https://jenkins.example.com --user your-username --token YOUR_API_TOKEN

# 不明な場合は対話プロンプト
python {skill_home}/jenkins-use/scripts/jenkins_client.py --label default configure

3. 接続確認: configure 実行後に info で接続を確認する。

python {skill_home}/jenkins-use/scripts/jenkins_client.py --label default info

• Python 3.8+（標準ライブラリのみ、追加インストール不要）
• Jenkins URL、ユーザー名、API トークン（Jenkins 管理画面 → ユーザー → API Token で生成）

接続情報の設定

「Jenkins を設定して」「接続情報を設定して」などのリクエストを受けたら、configure コマンドを実行して connections.yaml に保存する。

configure コマンドで設定（推奨）

# 対話形式（プロンプトで入力）
python {skill_home}/jenkins-use/scripts/jenkins_client.py configure

# オプションで直接指定
python {skill_home}/jenkins-use/scripts/jenkins_client.py configure \
  --url https://jenkins.example.com --user your-username --token YOUR_API_TOKEN

# ラベルを指定して複数環境を管理
python {skill_home}/jenkins-use/scripts/jenkins_client.py --label staging configure \
  --url https://staging.jenkins.example.com --user your-username --token YOUR_TOKEN

設定は {agent_dir}/connections.yaml（例: .github/connections.yaml）に保存される。 APIトークンを直接記述する場合は .gitignore に追加すること。

connections.yaml の直接編集

# .github/connections.yaml
jenkins:
  - label: default
    url: https://jenkins.example.com
    user: ${JENKINS_USER}    # 環境変数を参照
    token: ${JENKINS_TOKEN}

  - label: staging
    url: https://staging.jenkins.example.com
    user: your-username
    token: your_staging_token

テンプレートは {agent_dir}/connections.yaml.example（例: .github/connections.yaml.example）を参照。

接続情報の解決順序（上位優先）:

1. --url / --user / --token CLI オプション
2. connections.yaml（ワークスペース > グローバル）--label で接続先を切り替え可能
3. 環境変数 JENKINS_URL / JENKINS_USER / JENKINS_TOKEN
4. ワークスペース設定ファイル .jenkins.json（後方互換）

環境変数で設定

export JENKINS_URL=https://jenkins.example.com
export JENKINS_USER=your-username
export JENKINS_TOKEN=your_api_token

基本ワークフロー

Step 1: 接続確認

python scripts/jenkins_client.py info

Jenkins バージョンと接続状態を確認する。

Step 2: 操作を実行

目的に応じて以下のコマンドを使い分ける。

コマンドリファレンス

ジョブ一覧の取得

python scripts/jenkins_client.py list-jobs

ビルドのトリガー

# パラメータなしでビルド
python scripts/jenkins_client.py build --job my-pipeline

# パラメータ付きでビルド
python scripts/jenkins_client.py build --job my-pipeline \
  --params BRANCH=main ENV=production

戻り値: キューに入ったビルド番号（利用可能になるまで待機）

ビルド一覧の取得

# 直近10件
python scripts/jenkins_client.py list-builds --job my-pipeline

# 件数を指定
python scripts/jenkins_client.py list-builds --job my-pipeline --limit 20

ビルド状態の確認

# 最新ビルドの状態
python scripts/jenkins_client.py status --job my-pipeline

# ビルド番号を指定
python scripts/jenkins_client.py status --job my-pipeline --build 42

出力例:

Build #42
  Status : SUCCESS
  Started: 2025-01-15 10:30:00
  Duration: 3m 42s
  URL    : https://jenkins.example.com/job/my-pipeline/42/

ビルド完了まで待機

# デフォルト: 30分タイムアウト、10秒ポーリング
python scripts/jenkins_client.py wait --job my-pipeline --build 42

# タイムアウトとポーリング間隔を指定
python scripts/jenkins_client.py wait --job my-pipeline --build 42 \
  --timeout 3600 --interval 30

完了後にビルド結果（SUCCESS / FAILURE / ABORTED）を表示して終了する。

コンソールログの取得

# 最新ビルドのログ全体
python scripts/jenkins_client.py log --job my-pipeline

# ビルド番号を指定
python scripts/jenkins_client.py log --job my-pipeline --build 42

# 末尾 N 行のみ表示
python scripts/jenkins_client.py log --job my-pipeline --tail 100

# 実行中ビルドをストリーミング（完了まで追従）
python scripts/jenkins_client.py log --job my-pipeline --follow

リトライとタイムアウトの仕様

jenkins_client.py は以下の挙動をデフォルトで持つ:

リトライ対象: HTTP 5xx・接続エラー・タイムアウト。4xx（認証失敗など）はリトライしない。

エラー対処

使用例: ビルドして結果を確認

# 1. ビルドをトリガー
python scripts/jenkins_client.py build --job deploy-prod \
  --params VERSION=1.2.0

# 2. 完了まで待機（最大60分）
python scripts/jenkins_client.py wait --job deploy-prod \
  --timeout 3600

# 3. 失敗した場合はコンソールログを確認
python scripts/jenkins_client.py log --job deploy-prod --tail 200

詳細な API リファレンスは references/api-reference.md 参照。