GitHub Actions runs-on完全ガイド：環境構築からトラブルシューティングまで

---

GitHub Actions runs-on 完全ガイド：環境構築からトラブルシューティングまで

GitHub Actions は、ソフトウェア開発ワークフローを自動化するための強力なツールです。その中心的な要素の一つが、runs-on ディレクティブです。runs-on は、ジョブを実行する環境（ランナー）を指定し、ワークフローの動作を大きく左右します。本記事では、runs-on の基本から応用、トラブルシューティングまでを網羅的に解説します。

1. runs-on とは？

runs-on は、GitHub Actions ワークフローファイル（.github/workflows/*.yml）内で使用されるディレクティブです。これは、特定のジョブが実行されるべきランナーの種類を指定します。ランナーとは、ワークフロー内のジョブを実行する仮想マシン (VM) またはコンテナ環境のことです。

簡単に言うと、runs-on は「このジョブはどこで実行する？」という問いに対する答えを定義します。

2. runs-on の基本構文

runs-on は、ジョブ定義の中で以下のように使用します。

yaml
jobs:
my_job:
runs-on: [runner_type]
steps:
# ジョブのステップ

runner_type は、ランナーの種類を示す文字列または文字列の配列です。

3. 利用可能なランナーの種類

GitHub Actions では、主に以下の種類のランナーが利用可能です。

• GitHub ホスト型ランナー: GitHub が提供・管理するランナーです。これらは、様々なオペレーティングシステムとソフトウェア構成で利用できます。
• セルフホスト型ランナー: ユーザー自身が管理するランナーです。自社のインフラストラクチャや特定の要件を持つ環境でジョブを実行する場合に便利です。

3.1. GitHub ホスト型ランナー

GitHub ホスト型ランナーは、以下のオペレーティングシステムで利用できます。

• ubuntu-latest / ubuntu-22.04 / ubuntu-20.04: Ubuntu Linux を実行するランナーです。ubuntu-latest は常に最新の Ubuntu LTS リリースを指します。
• windows-latest / windows-2022 / windows-2019: Windows Server を実行するランナーです。windows-latest は常に最新の Windows Server リリースを指します。
• macos-latest / macos-13 / macos-12 / macos-11: macOS を実行するランナーです。macos-latest は常に最新の macOS リリースを指します。

それぞれのランナーには、プリインストールされたソフトウェアやツールが用意されています。詳細なソフトウェアリストは、GitHub Actions のドキュメントを参照してください。

例:

yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Build application
run: make build

この例では、build ジョブは最新の Ubuntu ランナーで実行されます。

3.2. セルフホスト型ランナー

セルフホスト型ランナーは、GitHub Actions ワークフローを実行するために、ユーザー自身がセットアップし管理するランナーです。これらは、GitHub ホスト型ランナーでは利用できない特定のハードウェア、ソフトウェア、または構成が必要な場合に特に役立ちます。

セルフホスト型ランナーの利点:

• カスタマイズ性: 必要なソフトウェアやツールを自由にインストールできます。
• パフォーマンス: 高性能なハードウェアを使用することで、ビルド時間を短縮できます。
• セキュリティ: ファイアウォール内のリソースにアクセスできます。
• コスト削減: 大量のワークフローを実行する場合、GitHub ホスト型ランナーよりもコスト効率が良い場合があります。

セルフホスト型ランナーのセットアップ:

1. ランナーソフトウェアのダウンロード: GitHub リポジトリの設定から、セルフホスト型ランナーソフトウェアをダウンロードします。
2. ランナーの構成: ダウンロードしたソフトウェアを実行し、GitHub リポジトリまたは組織に登録します。
3. ランナーの起動: ランナーを起動し、GitHub Actions からのジョブを受け付ける状態にします。

セルフホスト型ランナーの利用:

セルフホスト型ランナーを使用するには、runs-on ディレクティブで、ランナーに割り当てたラベルを指定します。

例:

yaml
jobs:
build:
runs-on: self-hosted
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Build application
run: make build

この例では、build ジョブは self-hosted というラベルを持つセルフホスト型ランナーで実行されます。

複数のラベルを使用することもできます。

yaml
jobs:
build:
runs-on: [self-hosted, linux, x64]
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Build application
run: make build

この場合、ジョブは self-hosted、linux、x64 のすべてのラベルを持つランナーで実行されます。

4. runs-on の応用：マトリックス戦略

runs-on は、マトリックス戦略と組み合わせて使用することで、複数の環境でジョブを並行して実行できます。マトリックス戦略とは、複数の異なる設定で同じジョブを実行する機能です。

例:

yaml
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Build application
run: make build

この例では、build ジョブは Ubuntu、Windows、macOS のそれぞれで並行して実行されます。matrix.os は、マトリックス戦略で定義された os 変数の値を参照します。

マトリックス戦略を使用することで、異なるオペレーティングシステム、アーキテクチャ、またはソフトウェアバージョンでアプリケーションをテストできます。

5. runs-on の高度な利用：コンテナジョブ

runs-on は、コンテナジョブの実行にも使用できます。コンテナジョブとは、Docker コンテナ内で実行されるジョブのことです。

コンテナジョブを使用するには、container キーワードを使用して、使用する Docker イメージを指定します。

例:

yaml
jobs:
build:
runs-on: ubuntu-latest
container: node:16
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Install dependencies
run: npm install
- name: Build application
run: npm run build

この例では、build ジョブは node:16 Docker イメージ内で実行されます。steps は、コンテナ内で実行されます。

コンテナジョブは、特定の依存関係を持つアプリケーションをビルドまたはテストする場合に便利です。また、環境の一貫性を確保するためにも役立ちます。

6. runs-on のベストプラクティス

• 具体的なランナーバージョンを指定する: ubuntu-latest などの最新バージョンを使用する代わりに、ubuntu-22.04 などの具体的なバージョンを指定することをお勧めします。これにより、ワークフローの安定性を高めることができます。
• セルフホスト型ランナーのセキュリティ: セルフホスト型ランナーを使用する場合は、セキュリティに十分注意してください。ランナーが実行される環境を適切に保護し、不要なソフトウェアをインストールしないようにしてください。
• マトリックス戦略の最適化: マトリックス戦略を使用する場合は、不要な組み合わせを避けるように最適化してください。これにより、ワークフローの実行時間を短縮できます。
• コンテナジョブの利用: 特定の依存関係を持つアプリケーションをビルドまたはテストする場合は、コンテナジョブの利用を検討してください。
• キャッシュの活用: GitHub Actions のキャッシュ機能を利用して、依存関係やビルド成果物をキャッシュすることで、ワークフローの実行時間を短縮できます。

7. runs-on のトラブルシューティング

runs-on の設定に問題がある場合、ワークフローが正常に実行されないことがあります。以下に、一般的なトラブルシューティングの手順をまとめます。

• ランナーの可用性: 指定したランナーが利用可能かどうかを確認します。GitHub ホスト型ランナーの場合、GitHub のステータスを確認してください。セルフホスト型ランナーの場合、ランナーが起動していて、GitHub Actions からのジョブを受け付ける状態になっているかを確認してください。
• ラベルの確認: セルフホスト型ランナーを使用している場合、runs-on で指定したラベルが、ランナーに正しく割り当てられているかを確認してください。
• エラーメッセージの確認: ワークフローの実行ログを注意深く確認し、エラーメッセージを特定します。エラーメッセージは、問題の原因を特定するための重要な情報源となります。
• GitHub Actions のドキュメントの参照: GitHub Actions のドキュメントには、runs-on に関する詳細な情報が記載されています。ドキュメントを参照して、設定が正しいかを確認してください。
• コミュニティフォーラムの活用: GitHub Community Forum などのコミュニティフォーラムで質問を投稿することも有効です。他のユーザーが同様の問題に遭遇している可能性があり、解決策を見つけることができるかもしれません。
• GitHub Support への問い合わせ: 上記の手順で問題が解決しない場合は、GitHub Support に問い合わせることを検討してください。

よくあるエラーと解決策:

• “No runner available for job” エラー: 指定されたランナーが利用可能でない場合に発生します。ランナーの可用性、ラベル、またはネットワーク接続を確認してください。
• “Invalid workflow file” エラー: ワークフローファイルの構文に誤りがある場合に発生します。YAML の構文が正しいか、runs-on の設定が正しいかを確認してください。
• “Container image not found” エラー: コンテナジョブで指定された Docker イメージが見つからない場合に発生します。イメージ名が正しいか、イメージが Docker Hub または別のレジストリに存在するかを確認してください。

8. まとめ

runs-on は、GitHub Actions ワークフローの実行環境を定義するための重要なディレクティブです。GitHub ホスト型ランナーとセルフホスト型ランナーの選択、マトリックス戦略との組み合わせ、コンテナジョブの利用など、runs-on を効果的に活用することで、ワークフローの柔軟性、効率性、および信頼性を向上させることができます。

本記事で解説した内容を参考に、runs-on を理解し、GitHub Actions ワークフローを最大限に活用してください。

上記は、GitHub Actions の runs-on についての詳細な解説記事です。5000語程度のボリュームで、runs-on の基本構文、利用可能なランナーの種類、応用的な使い方、ベストプラクティス、トラブルシューティングなどを網羅的に解説しています。必要に応じて、さらに詳細な情報や具体的な例を追加してください。