jenkins-rest-ops

jenkins-rest-ops

概要

このスキルを使うと、エージェントは curl でリモートアクセス REST API を直接呼び出して Jenkins の CI/CD 操作を実行できます。SDK も pip への依存もありません。Jenkins は パスアドレス方式です。ほとんどのオブジェクトの URL に api/json を追加して読み取り、アクションパスに POST して書き込みます。エージェントは呼び出し元が注入した認証情報を使用し、同梱のインデックスから CORE パスを見つけ、curl コマンドを組み立てて、JSON を解析します。実行可能な CORE の機能（トリガー／ポーリング／ステータス／コンソール／一覧表示に加え、ジョブの CRUD とビルド管理）をカバーし、Jenkins API の範囲内にとどまるよう意図されています（Jenkinsfile をリポジトリにコミットしたり、SCM の Webhook を設定したりはしません。これらは vcs の操作です）。Jenkins は公式の OpenAPI を提供していないため、CORE パスは公式のリモートアクセスドキュメントに基づいています。

有効化するタイミング

• ✅ ビルドをトリガー（build／buildWithParameters）し、結果が出るまで追跡する場合。
• ✅ ビルドの ステータス（result／building／duration）または コンソールログを読み取る場合。
• ✅ ジョブ、キュー、ノード、ビューを一覧表示／調査する場合。
• ✅ Jenkins API を使って ジョブの CRUD（createItem + config.xml による作成、コピー、削除、有効化／無効化）や、ビルド管理（ビルドの停止／削除）を行う場合。

次の場合は有効化しないでください：

• Jenkinsfile／パイプライン設定をリポジトリにコミットする必要がある場合、またはリポジトリを Jenkins に接続する SCM Webhook を設定する場合。これらは vcs の操作（GitHub／GitLab／Bitbucket の操作スキル）であり、Jenkins API の操作ではありません。（createItem による Jenkins ジョブの作成は対象範囲内ですが、パイプラインのソースをリポジトリにコミットする操作は対象外です。）
• 認証情報の設定だけが必要な場合。認証情報は呼び出し元から提供されます。このスキルは認証情報のプロビジョニングや解決を行いません（references/credentials.md を参照）。
• プラグインが提供するエンドポイントに依存する操作の場合。CORE API はプラグインに依存しませんが、プラグインのエンドポイントはインストール環境ごとに異なり、保証される機能の範囲外です。

ワークフロー

ステップ 1 — 注入された認証情報を受け取る

呼び出し元はすでにアカウントを解決し、この操作に必要な情報を注入しています。これを使用し、自分でレコードを探さないでください。コンテキストから次の情報を受け取ります。

• base_url、username、および capability（cicd）は、ファイルから読み取るのではなく、コンテキスト値として渡されます。
• 順序付きの読み込みルールに基づくトークン。コンテキストには変数の名前が含まれます。プロジェクトレベルの .env ファイルが存在し、その変数が定義されている場合はその値を使用し、そうでなければ同じ名前の環境変数を使用します（プロジェクトの .env が優先されます）。トークンの値はコンテキストの説明文に含まれず、変数名のみが含まれます。curl は環境変数から値を読み取ります。.env を見つけるためのスコープ解決やディレクトリ検索は行わないでください。また、対象はプロジェクトの .env であり、.envrc ではありません。

スクリプトで固定されている変数 base_url／username／JENKINS_TOKEN に割り当てます。認証には HTTP Basic を使用します：curl -u "$username:$JENKINS_TOKEN"。契約の全文は references/credentials.md を参照してください。

ステップ 2 — パスを見つける

公式のリモートアクセスドキュメントに基づく、信頼できる CORE パステーブル assets/endpoint-index.md を確認します。Jenkins はパスアドレス方式のため、パスはテンプレート（job/<name>/build）であり、すべてのジョブに適用されます。同梱の非公式 swaggy-jenkins 仕様にも記載されている範囲については、python3 scripts/endpoint.py <operationId> を実行すると、相互確認用のリクエスト／レスポンススキーマが出力されます（相互確認にしか使えない理由については references/patterns.md を参照してください）。

ステップ 3 — curl を組み立てて実行する

references/patterns.md のパターンを適用します。

• 認証： すべての呼び出しで -u "$username:$JENKINS_TOKEN" を指定します。
• 読み取り： GET <base_url>/<path>/api/json を使用します。レスポンスを小さく保つには ?tree=field[sub] を使います。?tree= に [角括弧] が含まれる場合は、必ず curl -g（--globoff）を渡します。これらは curl の glob メタ文字であり、指定しないと「bad range」（curl エラー 3）でリクエストが中断されます。
• 書き込み： POST を使用します。トークン認証ではトークンが CSRF の対象外となるため、crumb は不要です。403 No valid crumb の場合に限り、-H "$(bash scripts/crumb.sh)" を追加します。
• フォルダー： ネストの階層ごとに job/ を繰り返し、ジョブ名は URL エンコードします。

同梱の scripts/*.sh（trigger-build、poll-queue-item、build-status、console-log、list-jobs、crumb）は実例です。

ステップ 4 — ビルドでは非同期フローに従う

ビルドのトリガーは非同期で、ビルドではなくキュー項目を返します。

1. trigger-build.sh <job> [K=V …] → キュー項目の URL（Location ヘッダー）を出力します。
2. poll-queue-item.sh <queue-item-url> → ビルドが開始されるまでポーリングし、ビルド URL と番号を出力します。
3. result／building には build-status.sh <job> [<n>]、ログには console-log.sh <job> [<n>] を使います。

キュー項目が解決する前にビルド番号を読み取らないでください。ビルドはまだキューに入っている可能性があります。

ステップ 5 — レスポンスを処理する

• 読み取り： JSON が返されます（building が true の間、result は null です）。巨大なペイロードを避けるには ?tree= を使います。?depth=N はすぐにレスポンスを膨らませます。
• エラー： POST で 403 No valid crumb が返された場合は crumb を追加します（ステップ 3）。crumbIssuer で 404 が返された場合は CSRF が無効であり、crumb は不要です。それ以外の 401／403 は、トークンが無効または期限切れか、権限が不足していることを意味します。

ルール

必ず守るルール（違反禁止）：

• SDK も pip も使用しません。 API 呼び出しには curl を使います。ヘルパーは scripts/endpoint.py のみです（python3 の標準ライブラリのみを使用）。
• トークンの値を読み取ったり表示したりしません。 curl -u の引数で $JENKINS_TOKEN として参照する場合に限ります。サブプロセスは環境変数から読み取ります。トークンが保存されるのは .env（gitignore 対象）または環境変数のみです。
• ビルドのトリガーが返すのはビルドではなくキュー項目です。 ビルドのステータスを読み取る前に、必ず queue/item/<id>/api/json をポーリングして実行可能な状態になるまで待ちます。
• トークン認証は crumb の対象外です。 すべての POST で無条件に crumb を取得・付与しないでください。403 No valid crumb の場合のフォールバックとしてのみ付与します。
• swaggy-jenkins ではなく CORE インデックスを参照します。 パスには assets/endpoint-index.md（公式情報に基づく）を使います。同梱の swaggy-jenkins 仕様は非公式で不完全な照合用です。信頼できる情報源として使用しないでください。
• Jenkins API の範囲内にとどまります。 Jenkinsfile をコミットしたり、SCM Webhook を設定したりしないでください。これらは vcs 操作です。
• このスキルは認証情報を書き込みません。 認証情報は呼び出し元から提供されます。

推奨事項（変更可能）：

• レスポンスを小さく保つため、?depth=N より ?tree= によるフィールド選択を優先します。
• ログインパスワードより、ユーザーごとのAPI トークンを優先します（公式ドキュメントではパスワードの使用を推奨していません）。
• 完了したビルドには consoleText を使用し、実行中のビルドをストリーミングするには logText/progressiveText?start=<offset> を使用します。

注意点

• 非同期ビルドの落とし穴。 ビルドへの POST は 201 と Location: のキュー項目を返します。ビルド番号ではありません。直後に job/<name>/lastBuild を読み取ると、前のビルドが返される場合があります。まずキュー項目を .executable までポーリングしてください。
• キュー項目の有効期間は短いです。 キュー項目はビルド終了後、約 5 分間しか有効ではありません。速やかにポーリングし、.executable.url を取得してください。
• Crumb に関する混乱。 現行の Jenkins と API トークンを使用している場合、Crumb は不要です（2.96/2.107 以降、トークン認証は対象外です）。403 No valid crumb は Jenkins が古いか、パスワード認証を使用していることを意味します。その場合は取得してください。crumbIssuer/api/json が 404 を返す場合は CSRF が無効になっているため、スキップしてください。
• config.xml の Content-Type。 createItem では、リクエストボディを Content-Type: application/xml として送信する必要があります（--data-binary @config.xml を使用してください）。そうしないと XML がフォームデータとして不正に処理されます。
• フォルダーの階層。 フォルダー内のジョブは job/<folder>/job/<name> です。階層ごとに job/ を繰り返してください。job/<folder>/<name> は誤りです。
• buildWithParameters にはパラメーター化されたジョブが必要です。 パラメーターが反映されるのは、ジョブで宣言されている場合のみです。パラメーター化されていないジョブでは無視されます。まずジョブの設定でパラメーターを定義してください。
• パラメーター化されたジョブは /build を 400 Bad Request で拒否します。 上記とは逆のケースです。ジョブでパラメーターを宣言すると、POST job/<name>/build は 400 を返します。宣言済みのデフォルト値でビルドする場合でも、上書き指定を送らずに buildWithParameters を使用する必要があります。したがって、K=V 引数なしで trigger-build.sh <job> を実行すると（/build に POST するため）、パラメーター化されたジョブを起動できません。少なくとも 1 つの K=V（またはデフォルト値）を渡して、buildWithParameters に振り分けられるようにしてください。
• swaggy-jenkins は不完全で、癖があります。 同梱の仕様には buildWithParameters、consoleText、任意の job/<n>/<build>/api/json が含まれておらず、postJobBuild には実在しない json クエリパラメーターがモデル化されています。パスについては assets/endpoint-index.md を信頼してください。
• ビルド中は result が null です。 実行中のビルドでは building: true、result: null が返されます。null を失敗と見なさないでください。
• ポーリングのタイムアウトは「キューに残っている」という意味であり、「失敗」ではありません。 poll-queue-item.sh は約 3 分でポーリングを打ち切ります。空きエグゼキューターがない場合、静穏期間中、または .blocked／.stuck の状態でビルドが正当に待機していると、失敗していなくてもタイムアウトします。.why を確認して再度ポーリングし、誤って失敗と報告しないでください。
• 大きなレスポンス。 負荷の高いインスタンスでは、?tree=／?depth= を付けない api/json のレスポンスが大きくなる場合があります。必ずフィルターしてください。

アンチパターン

• キューをポーリングする前にビルドを読み取る。 最もよくある失敗です。起動時に返されたのはビルドではなくキュー項目です。まずポーリングしてください。
• すべての POST に Crumb を付ける。 トークン認証では対象外のため、無駄であり不適切です。Crumb は 403 の場合にのみ取得し、無効時の 404 にも対応してください。
• swaggy-jenkins を正式な情報源として信頼する。 非公式で不完全なため、照合のみに使用してください。正しい情報源は CORE インデックスです。
• トークンを出力する。 echo $JENKINS_TOKEN は絶対に実行せず、出力されるコマンドにトークンを貼り付けず、その値をファイルに書き込まないでください。curl -u 内で環境変数を参照してください。
• Jenkinsfile をコミットする／Webhook を設定する。 これは Jenkins API の操作ではなく vcs の操作であり、対象外です。
• SDK に手を出す。 jar ベースの Jenkins CLI や pip クライアントに頼る必要はありません。curl とインデックスで CORE の範囲をカバーできます。

出力

このスキルはAPI に副作用（要求された Jenkins 操作）を発生させ、解析済みの JSON（またはプレーンテキストのコンソールログ）を呼び出し元のエージェントに返します。独自のファイルは書き込みません（呼び出し元から注入された認証情報を使用するだけです）。ビルドの場合は、キュー項目 → ビルド URL／番号 → 最終的な result を報告します。読み取りの場合は、要求された JSON を返します。想定される利用者は、CI/CD 操作の実行を必要とする呼び出し元のエージェント（またはサブエージェント）です。シークレットが出力に含まれることはありません。

関連情報

• references/credentials.md — このスキルが使用する認証情報の契約です（呼び出し元が注入する base_url + username + 順序指定のトークン読み込みルール + HTTP-Basic ブリッジ）。
• references/patterns.md — 非同期ビルドのフロー、crumb のフォールバック、パス／フォルダー／レスポンスの整形、ステータスとコンソール、ジョブの CRUD、公式 OpenAPI を根拠として利用できない旨の注意事項です。
• REST を直接利用し、仕様を同梱するパターンは、ほかの API プロバイダーにも応用できます（同じ curl 主導の REST 操作の形を、Jenkins のパス指定型 API と HTTP-Basic トークン認証に合わせて調整します）。

段階的な情報開示

詳細な内容はサブフォルダーに格納され、必要な場合にのみ読み込まれます。

• references/credentials.md — 呼び出し元が注入するフィールド、順序指定のトークン読み込みルール、HTTP-Basic ブリッジ、秘密情報の適切な取り扱いです。ステップ 1 で読み込みます。
• references/patterns.md — 非同期ビルドとキューポーリング、crumb のフォールバック、パス／フォルダー／?tree=、ステータスとコンソール、ジョブの CRUD、根拠に関する注意事項です。ステップ 3～5 で読み込みます。
• references/sources.md — 出典（公式 Remote Access ドキュメント + 非公式な swaggy-jenkins フラグ）と「実際の環境で確認」する項目です。
• assets/endpoint-index.md — 正式な CORE パステーブルです（ステップ 2）。
• assets/swaggy-jenkins-openapi.json — 同梱された非公式の OpenAPI です（リゾルバー経由で照会し、全体を読み込むことはありません。部分的な照合に使用します）。
• scripts/endpoint.py + .validation.md — swaggy-jenkins を対象とする python3 リゾルバーです（ステップ 2 の照合）。
• scripts/{trigger-build,poll-queue-item,build-status,console-log,list-jobs,crumb}.sh + .validation.md — 検証済みのサンプルスクリプト 6 本です。

単独での使用（任意。必須ではありません）

これは、エージェントのフロー外で人が手動でスキルを実行するための便宜的な手順であり、スキルの依存要件ではありません。スキルの正式な契約は呼び出し元による注入（ステップ 1）です。この付録は手動で操作する場合のブリッジにすぎません。

手動で実行するには、API トークンを作成し（<base_url>/me/configure → API Token → Add new token）、値を Git で追跡しない .env に保存してから、3 つの変数を自分で設定します。

set -a; source .env; set +a                 # loads $JENKINS_CI_TOKEN, never prints it
export base_url="https://jenkins.example.com"
export username="my-user"
export JENKINS_TOKEN="$JENKINS_CI_TOKEN"
bash scripts/list-jobs.sh                    # verify auth
q="$(bash scripts/trigger-build.sh my-job BRANCH=main)"
bash scripts/poll-queue-item.sh "$q"

トークンの値は名前でのみ参照され、表示されることはありません。Jenkins トークンにはユーザーの全権限が付与されます（スコープなし）。失効可能なトークンを使用してください。

本文の予算

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下です — 毎回のターンでコンテキストに保持されるため、REST の詳細は references/ に格納します。
• assets/swaggy-jenkins-openapi.json は大きいため、ディスク上で照会し、コンテキストには読み込みません。