# ジョブの開始前または終了後にスクリプトを実行する

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

> \[!NOTE]
> GitHub Enterprise Server ホステッド ランナーは、現在 GitHub ではサポートされていません。

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

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

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

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

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

## スクリプトの記述

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

* **環境変数**: スクリプトには、既定の変数へのアクセス権があります。 完全な Webhook イベント ペイロードは、`GITHUB_EVENT_PATH` にあります。 詳しくは、「[変数リファレンス](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/variables#default-environment-variables)」をご覧ください。
* **ワークフロー コマンド**: スクリプトはワークフロー コマンドを使用できます。 詳しくは、「[GitHub Actions のワークフロー コマンド](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-commands)」をご覧ください。 スクリプトで環境ファイルを使うこともできます。 詳細については、「[環境ファイル](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-commands#environment-files)」を参照してください。

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

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

### 終了コードの処理

ジョブ前スクリプトの場合、終了コード `0` はスクリプトが正常に完了したことを示します。その後、ジョブの実行に進みます。 それ以外の終了コードがある場合、ジョブは実行されず、失敗とマークされます。 ジョブ前スクリプトの結果を確認するには、ログに `Set up runner` エントリがあるかどうかを確認します。 ログの確認の詳細については、「[ワークフロー実行ログの使用](/ja/enterprise-server@3.22/actions/how-tos/monitor-workflows/use-workflow-run-logs#viewing-logs-to-diagnose-failures)」を参照してください。

これらのスクリプトでの使用には、[`continue-on-error`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontinue-on-error) の設定はサポートされていません。

## スクリプトを実行する

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

> \[!NOTE]
> トリガーされたスクリプトは同期的に処理されるので、実行中はジョブの実行が禁止されます。

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

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

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

```bash
ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner/cleanup_script.sh
```

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

## トラブルシューティング

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

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

```bash
chmod +x PATH/TO/FILE
```

ワークフローを使用してスクリプトを実行する方法については、「[ワークフローにスクリプトを追加する](/ja/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/add-scripts)」を参照してください。

### タイムアウトなしの設定

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

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

スクリプトが実行中かどうかを確認するために、そのジョブのログを確認することができます。 スクリプトをトリガーしている環境変数に応じて、`Set up runner` または `Complete runner` のいずれかの個別の手順内にスクリプトが一覧表示されます。 ログの確認の詳細については、「[ワークフロー実行ログの使用](/ja/enterprise-server@3.22/actions/how-tos/monitor-workflows/use-workflow-run-logs#viewing-logs-to-diagnose-failures)」を参照してください。