ワークフローでのセルフホストランナーの利用

ワークフローで使用するセルフホスト ランナーをターゲットにするには、ランナーに割り当てられたラベル、グループ メンバーシップ、またはこれらの組み合わせに基づいて、それを行います。

セルフホストランナーのラベルについて

ラベルを使うと、セルフホストランナーの共有される特徴に基づき、ワークフローのジョブを特定の種類のセルフホストランナーに送れます。 たとえば、ジョブが特定のハードウェアコンポーネントやソフトウェアパッケージを必要とするなら、カスタムラベルをランナーに割り当て、そのラベルを持つランナー上でのみ実行されるようジョブを設定できます。

ジョブにセルフホステッド ランナーを指定するには、ワークフロー ファイルでセルフホステッド ランナーのラベルを使って runs-on を設定します。

セルフホステッド ランナーには self-hosted ラベルが付いている場合があります。 セルフホステッド ランナーを設定すると、既定では self-hosted ラベルが付与されます。 --no-default-labels フラグを渡すことでセルフホステッド ラベルが適用されないように設定できます。 ラベルを使用すると、オペレーティング システムやアーキテクチャなど、特定のランナーを探すオプションを作成できます。self-hosted で始まり (リストの最初にこれを示す必要があります)、必要に応じて追加のラベルを含むラベルの配列を指定することをお勧めします。 ラベルの配列を指定すると、指定したラベルをすべて持つランナーのキューにジョブが入れられます。

Action-runner-controller は複数のラベルには対応していません。また、self-hosted ラベルにも対応していない点にご注意ください。

カスタム ラベルと既定のラベルの作成については、「セルフホストランナーとのラベルの利用」を参照してください。

セルフホストランナーのグループについて

Organization レベルで定義されたセルフホステッド ランナーの場合は、共有特性を持つランナーを 1 つのランナー グループにグループ化して、ランナー グループをターゲットにするようにジョブを構成できます。

ご利用のジョブに対してセルフホステッド ランナー グループを指定するには、ワークフロー ファイルで runs-on.group を構成します。

ランナー グループの作成と管理について詳しくは、「グループを使用してセルフホストランナーへのアクセスを管理する」を参照してください。

リポジトリで使用可能なランナーの表示

リポジトリに repo: write アクセス許可を持つ場合は、リポジトリで使用できるランナーの一覧が表示されます。

1. GitHub で、リポジトリのメイン ページに移動します。

2. リポジトリ名の下にある [アクション] をクリックします。

   

3. 左サイドバーの [管理] セクションで、[ランナー] をクリックします。

4. ランナー一覧の上部にある [セルフ ホステッド] タブをクリックします。

5. リポジトリで使用可能なセルフ ホステッド ランナーの一覧を確認します。 この一覧には、セルフ ホステッド ランナーおよび、Actions Runner Controller で作成されたランナー スケール セット が含まれます。 詳しくは、「Actions Runner Controller について」を参照してください。

6. 必要に応じて、ランナーのラベルをコピーしてワークフローで使用するには、ランナーの右側にある をクリックし、[ラベルのコピー] をクリックします。

デフォルトラベルを使ったジョブの転送

セルフホストランナーは、GitHub Actionsに追加されたときに特定のラベルを自動的に受信します。 それらは、ランナーのオペレーティングシステムとハードウェアプラットフォームを示すために使われます。

• self-hosted: セルフホステッド ランナーに適用される既定のラベル。
• linux、windows、または macOS: オペレーティング システムに応じて適用されます。
• x64、ARM、または ARM64: ハードウェア アーキテクチャに応じて適用されます。

ワークフローのYAMLを使って、これらのラベルの組み合わせに対してジョブを送信できます。 この例では、3つのラベルすべてにマッチするセルフホストランナーが、ジョブを実行する資格を持つことになります。

runs-on: [self-hosted, linux, ARM64]

• self-hosted - セルフホステッド ランナー上でこのジョブを実行します。
• linux - Linux ベースのランナーのみを使います。
• ARM64 - ARM64 ハードウェア ベースのランナーのみを使います。

既定のラベルを付けずにそれぞれのセルフホステッド ランナーを作成するには、ランナーを作成するときに --no-default-labels フラグを渡します。 アクション ランナー コントローラーは、複数のラベルをサポートしていません。

カスタムラベルを使ったジョブの転送

カスタムラベルを作成し、セルフホストランナーに割り当てることがいつでもできます。 カスタムラベルを使えば、付けられたラベルに基づいて特定の種類のセルフホストランナーにジョブを送信できるようになります。

たとえば、特定の種類のグラフィック ハードウェアを必要とするジョブがある場合、gpu というカスタム ラベルを作成し、そのハードウェアが組み込まれているランナーに割り当てることができます。 割り当てられたすべてのラベルにマッチするセルフホストランナーが、そのジョブを実行できるようになります。

以下の例は、デフォルトとカスタムのラベルを組み合わせたジョブです。

runs-on: [self-hosted, linux, x64, gpu]

• self-hosted - セルフホステッド ランナー上でこのジョブを実行します。
• linux - Linux ベースのランナーのみを使います。
• x64 - x64 ハードウェア ベースのランナーのみを使います。
• gpu- このカスタム ラベルは、GPU ハードウェアが組み込まれたセルフホステッド ランナーに手動で割り当てられました。

これらのラベルは累積的に働くので、このジョブを処理できるセルフホスト ランナーには、4 つすべてのラベルがなくてはなりません。

グループを使用したジョブのルーティング

この例では、Ubuntu ランナーが ubuntu-runners というグループに追加されています。 runs-on キーは、ubuntu-runners グループ内の使用可能なランナーにジョブを送信します。

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: ubuntu-runners
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

ラベルとグループを使用したジョブのルーティング

グループとラベルを組み合わせる場合、ランナーはジョブを実行する資格を得るために両方の要件を満たす必要があります。

この例では、ubuntu-runners というランナー グループに、ラベル ubuntu-20.04-16core も割り当てられている Ubuntu ランナーが設定されています。 runs-on キーは group と labels を組み合わせて、ラベルが一致するグループ内の使用可能な任意のランナーにジョブがルーティングされるようにします。

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

セルフホストランナーのルーティングの優先順位

ジョブをセルフホステッド ランナーにルーティングする際に、GitHub ではジョブの runs-on ラベル やグループと一致するランナーを探します。

• GitHub によって、ジョブの runs-on ラベル またはグループ に一致するオンラインおよびアイドル状態のランナーが検出された場合は、そのランナーに、該当するジョブが割り当てられて送信されます。
  • 割り当てられたジョブをランナーが 60 秒以内に取得しない場合、新しいランナーが受け入れることができるように、ジョブはキューに再格納されます。
• GitHub によって、ジョブの runs-on ラベル またはグループ と一致するオンラインおよびアイドル状態のランナーが検出されない場合は、ランナーがオンラインになるまで、ジョブはキューに格納されたままになります。
• 24時間以上にわたってキューに残っていたジョブは失敗します。