Semaphore をお使いのツールに接続

外部イベントで事前定義のタスクテンプレートを選び、リクエストの値を受け付ける入力へ割り当てる場合は Webhook 連携を使います。タスクを開始してステータスを読むなど、アプリケーションに明示的なリソースと実行のフローが必要な場合は REST API を使います。いずれの場合も、自動化は Semaphore の設定済み実行モデルを通じて動作します。呼び出し元が何を送り、何を追跡する必要があるかで選んでください。

プロジェクトのエイリアスは、その配下の連携に設定されたマッチャーを評価し、リクエストに一致した連携を開始できます。連携固有のエイリアスは、マッチャーを評価せずに 1 つの連携を直接指定します。ブランチやイベント種別のルールで実行を制御したい場合、この違いは重要です。すべてのエイリアスで同じフィルターが適用されると考えず、エンドポイントを意識して選び、一致するペイロードと一致しないペイロードの両方をテストしてください。

必要なリクエストヘッダーや本文の項目を読み取り、文書化された環境値やタスクパラメーターへ割り当てる抽出ルールを設定します。パラメーターの割り当て先は、テンプレートが受け付けるプロンプトと一致させる必要があります。割り当ては具体的にしてください。リリースバージョンは、自由なコマンド断片ではなく、意図する入力として渡すべきです。意味上の検証が必要な値は自動化側で検証し、本番利用の前に項目が欠けている場合や想定外の項目がある場合もテストしてください。

API トークンは、その Semaphore ユーザーの権限で動作します。連携で意図する操作に合ったプロジェクトアクセスを持つ ID を使い、呼び出し元が保存するトークンを保護してください。API によってプロジェクトの認可を迂回することはできません。Webhook 連携でも、文書化されたリクエスト認証とエンドポイントの公開範囲を意識して設定してください。呼び出し元の認証と、生成されたタスクがインフラへのアクセスに使う認証情報は分けて管理します。

REST API を使う処理では、文書化された操作が返すタスク識別子を保持し、対応する API メソッドで状態と出力を確認してください。リクエストの成功は実行が要求されたことを意味し、インフラ作業が正常に完了したことを意味しません。サービスでは、リクエストエラー、待機中または実行中のタスク、完了結果を区別します。実際の実行証跡を調査する必要があるエンジニアには、タスクへのリンクを提示してください。

厳密に 1 回だけの実行や永続的な配信が保証されていると考えないでください。最初のリクエストが Semaphore に届いていても、外部サービスはタイムアウト後に再試行する場合があります。操作の影響に応じて重複処理と再試行の判断を設計し、必要に応じて基盤の自動化を冪等にします。元のイベントとサービスが追跡する実行の対応関係を維持し、エンジニアが重複配信や結果不明の配信を理解できるようにしてください。

このサイトのリファレンスは、Semaphore リリースに付属する Swagger/OpenAPI 文書を表示しています。そのため、操作、パス、スキーマは手書きの要約ではなく、特定のバージョンに対応します。/api-docs/ でリソース別に参照するか、クライアント生成に使う場合は元の文書を読めます。リリース間でエンドポイントやリクエストスキーマが変わる場合があるため、実際に動かすバージョンの仕様を必ず確認してください。

呼び出し元システムは Semaphore インスタンスへ到達できる必要がありますが、公開インターネットである必要はありません。呼び出し元がその内側で動くなら、プライベートネットワーク、VPN、内部ロードバランサーで十分です。私たちのマッチャーと抽出ルールの検証は、認証を無効にしたループバック専用リスナーで行ったもので、公開エンドポイントの手本ではありません。信頼するネットワークの外からエイリアスにアクセスできる場合は、対応する認証方式を設定し、ネットワーク層でも公開範囲を制限してください。

最初に影響のないタスクテンプレートへ連携を向け、curl などの HTTP クライアントでペイロードを自分で送信してください。一致しない本文を送り、タスクが現れないことを確認します。次に一致する本文を送り、タスクがちょうど 1 つ開始することを確認します。そのタスクの詳細画面を開くと、発生元として連携が記録され、抽出された値を実行で確認できます。これは私たちがローカルで使った手順と同じで、外部サービスが依存する前にマッチャーキーの誤りを検出できます。

はい。REST API は、プロジェクト、リポジトリ、インベントリ、認証情報、変数グループ、タスクテンプレート、その他の自動化リソースを対象とします。ポータルやインフラサービスからそれらを設定し、タスクを開始して、実行ステータスと出力を読み取れます。Pro はワークフローの実行と承認も API に公開するため、CI/CD パイプラインから複数ステップの操作全体を開始できます。エンドポイントのパラメーターと応答スキーマは OpenAPI リファレンスで確認してください。