カスタムイメージの使用

カスタムイメージ

カスタムイメージを作成することで、GitHub でホストされる大規模ランナーが使用する正確な環境を定義できます。カスタムイメージを使用すると、ツール、依存関係、および構成をプレインストールして、ワークフローを高速化し、ジョブ間の一貫性を向上させることができます。

ランナーがカスタムイメージを使用すると、"事前にウォームされた" 環境として機能し、ワークフローを実行するたびにではなく、イメージの作成時にパッケージとバイナリを 1 回ダウンロードすることで、ワークフローをより迅速に完了できます。カスタムイメージの詳細については、「ランナー画像」を参照してください。

カスタムイメージを使用するプロセスには、次の 3 つの主要な手順が含まれます。 1. イメージ生成ランナーの設定: より大きなランナーを作成して、カスタムイメージをビルドして格納します。 1. カスタムイメージの生成: イメージ生成ランナーを使用してワークフローを実行してカスタムイメージを生成します。 1. カスタムイメージのインストール: カスタムイメージを使用するランナーを作成します。

[前提条件]

カスタムイメージを作成する前に、次の要件が満たされていることを確認します。

        **ポリシー**: 組織または企業に対してカスタム イメージを有効にする必要があります。 エンタープライズ所有者は、カスタム イメージへのアクセスを管理し、[アクション] ポリシー設定でアイテム保持ポリシーを設定できます。 詳しくは、「[AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#custom-images)」をご覧ください。

```
        **アクセス許可**: カスタム イメージを作成および管理するには、組織またはエンタープライズ所有者であるか、 `CI/CD Admin` ロールを持っているか、次の詳細なアクセス許可を持つロールを持っている必要があります。  
```
- 組織でホストされているランナーのカスタムイメージを表示する
- 組織でホストされているランナーのカスタムイメージを管理する
- Organization のランナーとランナーグループを管理する
詳しくは、「カスタム組織の役割の情報」をご覧ください。

イメージ生成ランナーの設定

カスタムイメージを作成するには、まずイメージ生成ランナーを設定する必要があります。ランナーを作成するときは、ランナーに対して選択するプラットフォームが、ビルドするイメージのプラットフォームと一致している必要があります。ランナーのプラットフォームは、Linux x64、Linux ARM64、または Windows x64 のいずれかです。

より大きなランナーを作成します:
- 組織に関しては、「組織に大きなランナーを追加する」を参照してください。
- 企業の場合は、「大規模なランナーを企業に追加する」を参照してください。
ランナーを構成するときは、イメージ生成ランナーに対して次の構成を選択します。 * プラットフォーム: 作成するイメージのプラットフォーム (Linux x64、Linux ARM64、または Windows x64) に一致するサポートされているプラットフォームを選択します。 * イメージ: ビルドするイメージを選択し、[ このランナーを有効にしてカスタムイメージを生成する] チェックボックスをオンにします。
- GitHub所有のイメージから開始するか、クリーンな OS から開始する基本イメージを選択できます。
- ARM64 プラットフォームの場合は、プレインストールされたツールを使用して ARM で管理されているイメージを選択することもできます。
- ```
     **ランナー グループ**: ランナーがメンバーになるグループを選択します。 カスタム イメージが作成されると、このランナー グループ内のランナーのみが、そのイメージの新しいバージョンを生成できます。
```

カスタムイメージの生成

イメージ生成ランナーを作成したら、 snapshot キーワードを含むワークフローを実行してカスタムイメージを生成します。

イメージ生成用のワークフローを構成するには: * runs-on値を、作成したイメージ生成ランナーの名前に設定します。

次に示す文字列構文またはマッピング構文を使用して、 snapshot キーワードをジョブに追加します。 * snapshot キーワードを含む各ジョブは、個別のイメージを作成します。 1 つのイメージまたはイメージバージョンのみを生成するには、すべてのワークフローステップを 1 つのジョブに含めます。 * snapshot キーワードを含むジョブが正常に実行されるたびに、そのイメージの新しいバージョンが作成されます。

ワークフローの完了後、イメージが完全に生成され、使用できる状態になるまでに時間がかかる場合があります。プロビジョニング時間はランナーのサイズと構成によって異なり、大規模なランナーの場合は数時間かかる場合があります。

イメージは、ジョブが正常に完了したときにのみ生成されます。これにより、ワークフローが失敗したり、不完全な状態で終了したりしたときに、新しいイメージバージョンが作成されなくなります。

イメージが生成されると、ワークフローで使用できるようになります。カスタムイメージの管理の詳細については、「カスタムイメージの管理」を参照してください。

文字列構文

          `snapshot`と共に文字列構文を使用して、イメージ名を定義できます。 このメソッドは、新しいイメージを作成するか、同じ名前の既存のイメージに新しいバージョンを追加します。 この構文を使用してバージョン番号を指定することはできません。

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: my-custom-image
    steps:
      # Add any steps to download and setup any dependencies here

マッピング構文

          `snapshot`と共にマッピング構文を使用して、`image-name`と省略可能な`version`の両方を定義できます。 メジャーバージョンを指定すると、そのメジャーバージョンが既に存在する場合、マイナーバージョンは自動的にインクリメントされます。 パッチ バージョンはサポートされていません。

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

指定したメジャーバージョンが既に存在する場合、新しいイメージでは次のマイナーバージョンが使用されます (たとえば、1.0 は 1.1 になります)。
メジャーバージョンが存在しない場合、GitHub は新しいメジャーバージョン (2.0 など) を作成します。

パッチバージョンはサポートされていません。

カスタムイメージの管理

各イメージに関する詳細情報の表示、未使用のイメージまたは特定のバージョンの削除、および時間の経過に伴うイメージバージョンの追跡を行うことができます。

GitHub で、organization のメインページに移動します。
Organization 名の下で、[ Settings] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウンメニューを選び、 [設定] をクリックします。
左側のサイドバーで、[ Actions をクリックし、[ カスタム画像] をクリックします。
[カスタムイメージ] ページでは、組織または企業で作成されたすべてのカスタムイメージを表示できます。
特定のイメージに関する詳細を表示するには、イメージ名をクリックします。

カスタムイメージのインストール

カスタムイメージの準備ができたら、新しい GitHub でホストされる大規模ランナーにインストールできます。

より大きなランナーを作成するための手順に従ってください。
- 組織に関しては、「組織に大きなランナーを追加する」を参照してください。
- 企業の場合は、「大規模なランナーを企業に追加する」を参照してください。
ランナーを構成する場合: * プラットフォーム: イメージの生成に使用したのと同じプラットフォーム (Linux x64、Linux ARM64、または Windows x64) を選択します。 * イメージ: [ カスタム ] タブを選択し、一覧からカスタムイメージを選択します。
- イメージが表示されない場合は、適切なプラットフォームを選択していること、およびイメージが生成されたのと同じレベル (組織または企業) でランナーを作成していることを確認します。
- ```
     **イメージ バージョン**: 最新バージョンを自動的に使用するには [ **最新** ] を選択するか、ランナーをそのバージョンにピン留めする特定のバージョン番号を選択します。
```
  - 最新を選択すると、イメージの新しいバージョンが使用可能になった際に、ランナーが自動的に更新されます。ランナーを特定のバージョンにピン留めする場合は、後でアップグレードするためにランナーを手動で編集する必要があります。
- ```
     **サイズ**: イメージのサイズ以上のストレージを持つランナーサイズを選択してください。 たとえば、イメージが 8 コア ランナーで生成された場合は、8 コア以上を選択してこのイメージを実行します。
```
- ```
     **ランナー グループ**: このイメージを使用する必要があるリポジトリと共有されているランナー グループにランナーを割り当てます。
```

GitHub Actions ワークフロージョブで、runs-on キーをランナーの名前に設定してください。

jobs: 
  build:
    runs-on: my-custom-runner
    steps:
    # Add any steps for your workflow here

ワークフローを実行して、正常に完了したことを確認します。ジョブログには、[ジョブのセットアップ] セクションにイメージ名とバージョンが表示されます。

カスタムイメージの使用

この機能を使用できるユーザーについて

この記事の内容