ジョブ前後のスクリプトの実行

ジョブの直前または直後に、セルフホステッド ランナー上でスクリプトを自動的に実行できます。

この記事の内容

ジョブ前後のスクリプトについて

セルフホステッド ランナー上で、ジョブの実行前、またはジョブの実行完了後に自動的にスクリプトを実行することができます。 これらのスクリプトを使って、ランナー環境の構築または撤収、ディレクトリのクリーンアップなど、ジョブの要件をサポートすることができます。 また、これらのスクリプトを使って、ランナーの使用状況のテレメトリを追跡することもできます。

カスタム スクリプトは、ランナー上で特定の環境変数が設定されたときに自動的にトリガーされます。環境変数には、スクリプトの絶対パスを含める必要があります。 詳細については、後述する「スクリプトのトリガー」を参照してください。

以下のスクリプト言語がサポートされています。

  • Bash: bash を使います。sh にフォールバックできます。 実行するには、-e {pathtofile} を実行します。
  • PowerShell: pwsh を使います。powershell にフォールバックできます。 実行するには、-command \". '{pathtofile}'\" を実行します。

スクリプトの記述

カスタム スクリプトでは、次の機能を使用できます。

  • 環境変数: スクリプトには、既定の変数へのアクセス権があります。 完全な Webhook イベント ペイロードは、GITHUB_EVENT_PATH にあります。 詳しくは、「変数に情報を格納する」を参照してください。
  • ワークフロー コマンド: スクリプトはワークフロー コマンドを使用できます。 詳しくは、「GitHub Actions のワークフロー コマンド」をご覧ください。 スクリプトで環境ファイルを使うこともできます。 詳細については、「環境ファイル」を参照してください。

スクリプト ファイルを正常に実行するには、.sh や .ps1 など、該当する言語のファイル拡張子を使う必要があります。

注: スクリプトを使って機密情報をコンソールに出力することは避けてください。リポジトリに対して読み取りアクセス権を持つユーザーが UI ログの出力を確認する可能性があります。

終了コードの処理

ジョブ前スクリプトの場合、終了コード 0 はスクリプトが正常に完了したことを示します。その後、ジョブの実行に進みます。 それ以外の終了コードがある場合、ジョブは実行されず、失敗とマークされます。 ジョブ前スクリプトの結果を確認するには、ログに Set up runner エントリがあるかどうかを確認します。 ログの確認について詳しくは、「ワークフロー実行ログの使用」をご覧ください。

これらのスクリプトでの使用には、continue-on-error の設定はサポートされていません。

スクリプトのトリガー

カスタム スクリプトはランナー上に配置する必要があります。ただし、actions-runner アプリケーション ディレクトリには格納しないでください。 スクリプトは、ランナー サービスを実行しているサービス アカウントのセキュリティ コンテキストで実行されます。

注: トリガーされたスクリプトは同期的に処理されるので、実行中はジョブの実行がブロックされます。

スクリプトへの絶対パスを含む次の環境変数をランナーが持っている場合、スクリプトは自動実行されます。

  • ACTIONS_RUNNER_HOOK_JOB_STARTED: この環境変数に定義されているスクリプトは、ジョブがランナーに割り当てられ、ジョブの実行が開始される前に開始されます。
  • ACTIONS_RUNNER_HOOK_JOB_COMPLETED: この環境変数で定義されているスクリプトは、ワークフローで定義されているすべての手順が実行された後、ジョブの終了時に開始されます。

これらの環境変数を設定するには、オペレーティング システムに追加するか、セルフホステッド ランナー アプリケーション ディレクトリ（つまり、ランナー・ソフト ウェアをダウンロードして解凍したディレクトリ）内の .env というファイルに追加します。 たとえば、次の .env エントリがあると、各ジョブが実行される前に、/opt/runner/cleanup_script.sh というランナーマシン上に保存されたスクリプトを自動実行します。

ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner/cleanup_script.sh

注: ACTIONS_RUNNER_HOOK_JOB_COMPLETED で定義されているスクリプトは、ジョブの最後 (ジョブが完了する前) に実行されます。 そのため、自動スケーリングの実装の一部としてランナー マシンを削除するなど、ランナーを中断する可能性があるユース ケースには適していません。

トラブルシューティング

アクセス許可は拒否されました

スクリプトを実行しようとしたときに "アクセス許可が拒否されました" というエラーが表示される場合は、スクリプトが実行可能であることを確認してください。 たとえば、Linux または macOS 上のターミナルでは、次のコマンドを使用してファイルを実行可能にすることができます。

chmod +x PATH/TO/FILE

ワークフローを使用してスクリプトを実行する方法については、「ワークフローにスクリプトを追加する」を参照してください。

タイムアウトなしの設定

現在、ACTIONS_RUNNER_HOOK_JOB_STARTED または ACTIONS_RUNNER_HOOK_JOB_COMPLETED が実行するスクリプトに使用できるタイムアウト設定はありません。 そのため、スクリプトにタイムアウト処理を追加することを検討できます。

ワークフロー実行ログの確認

スクリプトが実行中かどうかを確認するために、そのジョブのログを確認することができます。 スクリプトをトリガーしている環境変数に応じて、Set up runner または Complete runner のいずれかの個別の手順内にスクリプトが一覧表示されます。 ログの確認について詳しくは、「ワークフロー実行ログの使用」をご覧ください。