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

ワークフロー Pro

ワークフローを使うと、複数のタスクテンプレートを分岐、承認、時間待ちを含む有向グラフ (DAG) として連結できます。ワークフローの実行は各ステップの完了に合わせて自動的に進みます。グラフは ビジュアルエディターで一度設計し、その後はワークフローのページから実行を開始します。

備考

ワークフローは Semaphore Pro の機能です。ワークフローのメニュー項目は、サブスクリプションに 含まれている場合にのみ表示されます。

概要​

ワークフローは次の要素で構成されます。

  • ノード — グラフ内のステップです（テンプレートの実行、承認の待機、一定時間の待機、 メモによる注記）。
  • エッジ — ノード間の接続です。それぞれに 条件 のラベルが付き、後続のノードを いつ開始するかを制御します。

ワークフローを開始すると、Semaphore は ワークフローの実行 を作成します。進行はサーバーが 制御します。タスクが完了し、承認が解決され、待機時間が経過するたびに、エッジの条件に従って 後続のノードが開始されます。

ワークフローの作成​

  1. プロジェクトを開き、ワークフロー に移動します。
  2. 新しいワークフロー をクリックします。
  3. グラフィカルエディターで次の操作を行います。
    • パレットからキャンバスにノードをドラッグします。
    • あるノードの出力ハンドルから別のノードへドラッグして、ノードを接続します。
    • ノードまたはエッジをクリックすると、サイドパネルでそのプロパティを編集できます。
  4. 名前 を設定します（必要に応じて、実行のバージョン管理用に 開始バージョン も設定します）。
  5. 問題 パネルに表示されている問題を解消し、保存 をクリックします。

ワークフローのエディター

エディターは保存前にグラフを検証します。有効なワークフローには、少なくとも 1 つのノードがあり、 開始ノードがちょうど 1 つ（入力エッジを持たないノード）あり、循環がなく、実行可能なすべての ノードの構成が完了している必要があります。

ノードの種類​

種類目的
タスクタスクテンプレートを実行します。タスクパラメーター により、ノードごとにテンプレートのパラメーター（インベントリ、変数グループ、Ansible の limit、追加の CLI 引数）を上書きできます。
承認権限を持つユーザーが承認または却下するまで、実行を一時停止します。必要に応じてタイムアウト（秒）と承認メッセージを設定できます。
待機設定した秒数だけ待ってから、後続のノードに進みます。冷却期間、メンテナンスウィンドウ、依存するステップの間隔調整などに便利です。
メモキャンバス上の自由形式の注記です。メモのノードは実行されず、エッジで接続されることもありません。ドキュメント用の要素です。

合流​

複数の入力エッジを持つノードは、上流のノードの すべて の完了を必要とするか（既定）、 いずれか 1 つの完了で進むかを指定できます。ノードのプロパティパネルで 合流 を設定します。

待機ノード​

待機ノードは、設定した時間（最短 1 秒）だけワークフローの実行を一時停止します。待機中は 次のようになります。

  • 実行は running のステータスのままです。
  • 実行のビューでは、待機ノードにカウントダウンがリアルタイムで表示されます。
  • エッジで接続された後続のノードは、待機が完了するまで開始されません。

待機が有効な間にワークフローの実行が 停止 された場合、待機はキャンセルされ、実行は stopped のステータスで終了します。

承認ノード​

実行が承認ノードに到達すると、誰かが承認または却下するまでステータスが approval に 変わります。実行のビューに承認／却下の操作が表示されます。却下された承認は、接続されている エッジの条件に従って実行を失敗させます。

エッジの条件​

各エッジには、後続のノードがいつ実行可能になるかを決める条件があります。

条件上流のノードが次の状態になったときに後続が開始します
成功時正常に完了したとき（既定）。
失敗時エラーで完了したとき。
常に終了状態（成功または失敗）のいずれかで完了したとき。

失敗時 の分岐は、補償処理や通知に使用します。結果に関係なく次のステップを実行する場合は 常に を使用します。

実行と監視​

  • ワークフローを実行 — ワークフローの一覧から新しい実行を開始します。
  • 実行のビュー — 各ノードのステータス（実行中、成功、失敗、承認、待機のカウントダウン）を リアルタイムで表示する全画面のグラフです。
  • 停止 — 実行が running または approval の間、run_project_tasks を持つユーザーは 実行を停止できます。実行中のすべてのタスクが停止され、保留中の承認は却下され、実行は stopped としてマークされます。

実行のステータス: running、approval、success、failed、stopped。

実行のバージョン管理​

ワークフローに 開始バージョン（たとえば 1.0.0）を設定すると、各実行にバージョンの ラベルが付きます。Semaphore はビルドテンプレートと同様に、実行ごとにバージョンを増加させます。

出力と入力​

タスクノードは、後続のノードに構造化されたデータを引き渡すことができます。タスクは 出力を生成 します。 出力とは名前付きの値からなる JSON オブジェクトで、タスクが成功するとタスクとともに保存されます。 次のタスクノードへの接続は 入力を受け渡し ます。つまり、直前のノードの出力で、そのノードの テンプレートのサーベイ変数を埋めます。受け渡されるのはファイルではなく、値だけです。

出力の生成​

ワークフローの実行によって開始されたすべてのタスクは、環境変数 SEMAPHORE_OUTPUTS_FILE を受け取ります。 これは、そのタスク専用に作成された空のファイルのパスです。タスクがこのファイルに JSON オブジェクトとして 書き込んだ内容が、そのタスクの出力になります。

アプリ出力の生成方法
Ansibleper_host: false（既定）を指定した ansible.builtin.set_stats。同梱の semaphore_outputs コールバックプラグインが、集計された実行の統計をファイルに書き込みます。ホストごとの統計は出力になりません。
Terraform, OpenTofu, Terragrunt実行が成功した後、output -json から自動的に取得されます。タスク自身がファイルに書き込んだ値は、同じ名前の取得された出力より優先されます。
Bash, Python, PowerShell, Pulumiスクリプトがファイルに書き込みます。
# Bash: 出力ファイルに書き込む
cat > "$SEMAPHORE_OUTPUTS_FILE" <<EOF
{"image_tag": "1.4.2", "replicas": 3, "subnet_ids": ["subnet-1", "subnet-2"]}
EOF
# Ansible: set_stats が出力になる
- name: Publish the image tag for the next nodes
  ansible.builtin.set_stats:
    data:
      image_tag: "{{ built_tag }}"

ルール:

  • 出力は、タスクが 成功 した場合にのみ読み取られます。失敗または停止したタスクには出力がないため、 失敗時 の分岐は、失敗したノードから何も受け取りません。
  • 出力の名前は ^[A-Za-z_][A-Za-z0-9_-]*$ に一致します。値には、文字列、数値、真偽値、リスト、 オブジェクトなど、任意の JSON の値を使用できます。
  • 制限: ファイルは最大 256 KB で、出力は最大 100 個、それぞれ最大 32 KB です。
  • ファイルが存在しないか空の場合は「出力なし」を意味します。JSON オブジェクトでないファイル、不正な名前を 使用しているファイル、制限を超えるファイルは タスクを失敗させ、その理由がタスクのログに記録されます。
  • 保存できない Terraform の出力（sensitive が指定されたもの、大きすぎるもの、名前が不正なもの、 制限を超えるもの）はスキップされ、タスクのログとタスクの 出力 (Outputs) パネルに 未取得 (Not captured) として一覧表示 されます。これらがタスクを失敗させることはありません。

入力の受け渡し​

タスクノードで終わる接続をクリックすると、そのサイドパネルに 入力 (Inputs) セクションがあります。

  • 名前で受け渡し（既定）。送り元のノードの出力のうち、名前が送り先のテンプレートのサーベイ変数と 一致するものが、その変数に入ります。一致する変数のない出力は無視されます。ハイフンを含む Terraform の 出力は有効な変数名にならないため、受け渡されません。
  • 入力を明示的にマッピング (Map inputs explicitly)。チェックボックスをオンにすると、一覧に指定したペア（送り先の テンプレートのサーベイ変数と、その値の元になる出力のキー）だけが受け渡されます。一覧が空の場合は 何も受け渡されません。ワークフローに完了した実行があると、パネルはその実行で生成されたキーを候補として 表示し、取得されなかったキーには印を付けます。

どの接続からも値が入らない変数には、ノードに設定された値が、それもなければ変数のデフォルト値が使われます。 値のない 必須 の変数があると、ノードのタスクは開始前に失敗し、その変数名を示すログ行が記録されます。 そのため、実行はその 失敗時 のエッジに従います。

値は変数のタイプに変換されます。int 変数は数値または数字の文字列を受け付け、enum または select 変数は自身の選択肢のみを受け付け、string または text 変数は任意の値を受け付けます（オブジェクトや リストはコンパクトな JSON として渡されます）。タイプに合わない値は無視され、その理由がタスクのログに 記録され、フォールバックの値が適用されます。

承認ノードと待機ノード は出力をそのまま通過させます。task → approval → task でもデータは 受け渡され、最後の接続のモードが適用されます。

1 つのノードへの複数の接続。 送り元が成功した接続は、それぞれ値を提供します。2 つの接続が同じ変数を 埋める場合は、明示的なマッピングが名前による受け渡しより優先されます。同じ種類どうしでは先に作成された 接続が優先されるため、実行のたびに同じ結果になります。優先された接続はタスクのログに記録されます。

The connection panel in by-name mode: matched survey variables are ticked

The connection panel with explicit mapping: one output key per survey variable

確認できる場所​

  • 実行のビュー では、出力を生成したすべてのノードに N 個の出力 (N outputs) のバッジが表示されます。
  • タスクのダイアログ には、値と 未取得 の一覧を含む 出力 のテーブルがあります。
  • 接続から値を受け取ったタスクのログは、変数ごとの 1 行から始まります（例: Input "image_tag" <- output "image_tag" of node 3 (task #41)）。そのため、各値の出所は その値自体の 1 行上に示されます。

Run view: nodes that produced outputs carry a badge

Task dialog, Details tab: the Outputs table

制限事項​

  • 出力は保存され、タスクを閲覧できるすべてのユーザーに平文で表示されます。出力を通じて シークレットを渡さないでください。 secret タイプのサーベイ変数は、接続から値を埋めることは できません。
  • 出力は値であり、コードではありません。Ansible はそれらをリテラルの文字列として受け取り、値に 含まれる Jinja2 の式は評価されません。
  • リモートのランナー上のタスクも、サーバー上のタスクと同様に出力を生成し、受け取ります。ランナーの Docker または Kubernetes のエグゼキューターで実行されるタスクは、まだ出力を生成しません。 その旨はタスクのログに記録されます。

環境変数​

ワークフローによって開始されたタスクは、すべてのタスクが受け取る変数に加えて、次の変数を受け取ります。

変数値
SEMAPHORE_WORKFLOW_IDワークフローの ID
SEMAPHORE_WORKFLOW_RUN_ID現在の実行の ID
SEMAPHORE_WORKFLOW_VERSION現在の実行のバージョン（ある場合）
SEMAPHORE_WORKFLOW_URL実行ページへのリンク（例：https://semaphore.example.com/project/1/workflows/7/runs/42。サーバー設定の web_host が必要です）
SEMAPHORE_OUTPUTS_FILEタスクが出力を書き込むファイルのパス

これらの変数は Ansible や Terraform を含むすべてのアプリケーションで設定され、リモートランナーで実行されるタスクにも渡されます。

権限​

  • ワークフローの管理（作成、編集、削除）には、プロジェクトのリソース管理の権限が必要です。
  • ワークフローの実行には run_project_tasks が必要です。
  • 承認の解決には、適切なプロジェクトのアクセス権が必要です（そのプロジェクトでタスクを 実行できるユーザーと同じです）。

API​

ワークフローのテンプレートと実行は /api/project/{project_id}/workflows で利用できます。リクエストとレスポンスのスキーマ （delay ノードのフィールド（delay_seconds）、エッジの input_mode と input_mappings、 実行の詳細（GET …/runs/{run_id}）に含まれる各タスクの artifacts ドキュメント、停止のエンドポイント （POST …/runs/{run_id}/stop）を含む）については、API ドキュメントを 参照してください。