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

ランナー

semaphore runner コマンドは、Semaphore をランナーモードで実行し、サーバーへの ランナーの登録を管理します。ランナーは、Semaphore サーバーとは別のマシン上でタスクを 実行します。

semaphore runner --help
ヒント

ランナーの仕組みとサーバー側の設定方法については、 ランナーガイドを参照してください。

サブコマンドなしで semaphore runner を実行すると、ヘルプが表示されるだけです。 次のサブコマンドがあります:

コマンド用途
runner setupランナーの設定ファイルを対話的に作成します (トークンが指定された場合は登録も行います)。
runner register登録トークンを使ってサーバーにランナーを登録します。
runner startランナーモードで実行し、タスクの受け付けを開始します。
runner unregisterサーバーからランナーの登録を削除します。

すべてのサブコマンドは、ランナーの設定ファイルを指定するグローバルフラグ --config <path> (および環境変数のみで実行するための --no-config) を受け付けます。

対話型セットアップ (runner setup)​

対話型のセットアップを順に進め、ランナーの設定ファイルを書き出します。登録トークンが 利用可能な場合 (プロンプトで入力するか、SEMAPHORE_RUNNER_REGISTRATION_TOKEN で設定)、 すぐにサーバーにランナーを登録します。

semaphore runner setup --config /path/to/config.runner.json

設定ファイルの書き出し先を選択するには --config <path> を渡します。指定しない場合、 セットアップは出力ディレクトリ (デフォルト: カレントディレクトリ) を尋ね、そこに config.runner.json を書き出します。

完了すると、ランナーを起動するためのコマンドが表示されます。例:

# Run in the foreground:
./semaphore runner start --config /path/to/config.runner.json

# Run as a daemon:
nohup ./semaphore runner start --config /path/to/config.runner.json &

セットアップを再実行する代わりに、生成された設定ファイルを後から手動で編集することも できます。

ランナーの設定オプション​

設定ファイルの runner ブロック内のフィールド:

フィールド環境変数説明
token / token_fileSEMAPHORE_RUNNER_TOKEN / SEMAPHORE_RUNNER_TOKEN_FILEランナーの認証トークン (登録時に発行されます)。
—SEMAPHORE_RUNNER_REGISTRATION_TOKEN登録トークン。環境変数のみで指定でき、ファイルには書き込まれません。
registration_token_fileSEMAPHORE_RUNNER_REGISTRATION_TOKEN_FILE登録トークンを含むファイルのパス。
nameSEMAPHORE_RUNNER_NAMEサーバー上に表示されるランナー名。
tagsSEMAPHORE_RUNNER_TAGSプロジェクトのランナー振り分けに使用するタグの JSON 配列。
webhookSEMAPHORE_RUNNER_WEBHOOKこのランナーにタスクがキューイングされたときにサーバーが呼び出す URL。
enabledSEMAPHORE_RUNNER_ENABLEDランナーがタスクを受け付けるかどうか。
project_idSEMAPHORE_RUNNER_PROJECT_IDプロジェクトレベルのランナーのプロジェクト ID。グローバルランナーの場合は省略します。
check_interval_secondsSEMAPHORE_RUNNER_CHECK_INTERVAL_SECONDSポーリング間隔 (秒)。デフォルト: 1。
max_parallel_tasksSEMAPHORE_RUNNER_MAX_PARALLEL_TASKS同時実行タスクの最大数。デフォルト: 9999。
one_offSEMAPHORE_RUNNER_ONE_OFF1 つのジョブを処理した後に終了します。Webhook によってオンデマンドで起動されるランナーに便利です。

セットアップの詳細はランナーを、オプションの全一覧は 設定を参照してください。

ランナーの登録 (runner register)​

サーバーにランナーを登録し、発行されたランナートークンを設定ファイルに保存します (既存のトークンは上書きされます)。サーバー側で runner_registration_token が設定されている 必要があり、ここではその同じトークンを渡します。

# Token read from a file:
semaphore runner register --registration-token-file /path/to/token --config /path/to/config.runner.json

# Token piped from stdin:
echo "$REGISTRATION_TOKEN" | semaphore runner register --stdin-registration-token --config /path/to/config.runner.json

# Token from the environment:
SEMAPHORE_RUNNER_REGISTRATION_TOKEN="$REGISTRATION_TOKEN" semaphore runner register --config /path/to/config.runner.json
フラグ説明
--registration-token-file <path>登録トークンをファイルから読み取ります。
--stdin-registration-token登録トークンを標準入力から読み取ります。
--name <name>登録に使用するランナー名。
--tags <tags>ランナーのタグ。カンマ区切り、またはフラグを繰り返して指定します (例: --tags a,b や --tags a --tags b)。
--webhook <url>ランナーの Webhook URL。
--enabledサーバー上でランナーを有効または無効にします。デフォルトは true です。無効な状態のランナーとして登録するには --enabled=false を渡します。
--project-id <id>指定したプロジェクトのプロジェクトレベルランナーとして登録します。省略した場合 (または 0 の場合)、ランナーはグローバルランナーとして登録されます。

実際に渡したフラグのみが適用されます。--name、--webhook、--tags、--enabled は、 コマンドラインで指定した場合にのみ、設定ファイルおよび環境変数の対応する値を上書きします。

登録トークンの取得元​

登録時、Semaphore は次の順序で、最初に利用可能なソースから登録トークンを解決します:

  1. --registration-token-file フラグ。
  2. 設定ファイルの registration_token_file 設定 (または SEMAPHORE_RUNNER_REGISTRATION_TOKEN_FILE)。
  3. --stdin-registration-token が渡された場合の標準入力。
  4. 環境変数 SEMAPHORE_RUNNER_REGISTRATION_TOKEN。

トークンファイルが存在するものの空である場合はエラーになります。どのソースからもトークンが 得られない場合、トークンなしで登録が試行され、サーバーによって拒否されます。

ランナーの起動 (runner start)​

ランナーを起動し、サーバーに接続してタスクの受け付けを開始します。登録済みのランナーを オンラインに保つために実行するコマンドです。

semaphore runner start --config /path/to/config.runner.json
フラグ説明
--auto-registerランナーがまだ登録されていない場合 (つまり設定にランナートークンがない場合)、起動前に登録します。
--register--auto-register のエイリアス。

--auto-register を指定した場合、設定に token がなければ、Semaphore は registration_token_file (または SEMAPHORE_RUNNER_REGISTRATION_TOKEN_FILE) または SEMAPHORE_RUNNER_REGISTRATION_TOKEN から登録トークンを読み取り、成功するまで 5 秒ごとに 登録を再試行し、設定を再読み込みしてから起動します。これは、コンテナなどで初回起動時に 自身を登録するランナーに便利です。

runner start は --registration-token-file や --stdin-registration-token を受け付けません。 これらのフラグは runner register 専用です。

ランナーの登録解除 (runner unregister)​

設定ファイルのランナートークンを使って、サーバーからランナーの登録を削除します。

semaphore runner unregister --config /path/to/config.runner.json