メインコンテンツまでスキップ

インテグレーション

インテグレーションを使用すると、GitHub や GitLab などの外部サービスと Semaphore の間の連携を確立できます。

インテグレーションの一覧

プロジェクトの Webhook URL は一覧の上に表示されます。各インテグレーションには名前と、起動するテンプレートがあります。インテグレーションをクリックすると、マッチャーと値の抽出ルールを設定できます。

インテグレーションの詳細

インテグレーションを使用すると、専用のエンドポイント（エイリアス）を呼び出して特定のテンプレートをトリガーできます。エンドポイントには、次のいずれかの認証方式を設定できます。

  • GitHub Webhooks
  • トークン
  • HMAC (SHA-256)
  • HMAC (SHA-512)
  • 認証なし

エイリアスは次の形式の URL を表します: /api/integrations/<random_string>。GET と POST のリクエストに対応しています。

HMAC 認証​

HMAC 認証方式（hmac / SHA-256 および hmac-sha512 / SHA-512）は、Webhook の本文が共有シークレットで署名されていることを検証します。

次の項目を設定します。

  1. Auth header — 署名を格納するリクエストヘッダー（例: X-Signature または X-Hub-Signature-256）。
  2. Auth secret — キーストアのログイン/パスワード認証情報。Semaphore は パスワード の値を HMAC シークレットとして使用します。

送信側は、未加工のリクエスト本文に対する HMAC ダイジェストを プレフィックスのない16進数 でこのヘッダーに設定する必要があります（sha256= / sha512= プレフィックスは付けません）。Semaphore は、設定されたシークレットを使用して本文から計算した HMAC-SHA256 または HMAC-SHA512 と比較します。

OpenSSL を使用した SHA-512 の例:

SECRET='your-webhook-secret'
BODY='{"event":"deploy"}'
SIG="$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "$SECRET" | awk '{print $2}')"

curl -X POST "https://semaphore.example.com/api/integrations/<alias>" \
  -H "Content-Type: application/json" \
  -H "X-Signature: ${SIG}" \
  --data "$BODY"

マッチャー​

マッチャーでは、受信リクエストのパラメーターを定義できます。これらのパラメーターが一致すると、テンプレートが呼び出されます。

値の抽出ルール​

抽出ルールを使用すると、リクエストのヘッダーまたはボディ（JSON フィールドまたは文字列）からデータを取得し、タスクに渡せます。抽出された各値には 変数の種類 があります。

  • 環境変数: 値がタスクの環境変数に追加され、変数グループの同名の変数を上書きします。
  • タスクパラメーター: 値がタスクのパラメーター（たとえばサーベイ変数やプロンプト）になります。

タスクパラメーター​

インテグレーションは、パラメーター付きでタスクをトリガーできます。値の抽出ルールを使用してタスクパラメーター用の JSON ペイロードを構築し、プロンプトで渡される値を受け取れるようテンプレートを設定してください。

エイリアスとマッチャーに関する注意​

プロジェクトのエイリアス（インテグレーション一覧の上に表示される URL）は、そのプロジェクトのすべてのインテグレーションで共有されます。Semaphore は各インテグレーションのマッチャーを確認し、マッチャーが一致したテンプレートを起動します。インテグレーションは独自のエイリアスを持つこともでき、そのエイリアスへのリクエストでは、マッチャーを評価せずにそのインテグレーションが起動します。必要に応じてトークンまたは HMAC による認証を優先し、パラメーターは抽出ルールで渡してください。