カスタムイメージの使用

カスタムイメージ

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

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

カスタムイメージを使用するプロセスには、次の 3 つの主要な手順が含まれます。

イメージ生成ランナーの設定: カスタムイメージをビルドして格納するより大きなランナーを作成します。
カスタムイメージの生成: イメージ生成ランナーを使用してワークフローを実行してカスタムイメージを生成します。
カスタムイメージのインストール: カスタムイメージを使用するランナーを作成します。

[前提条件]

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

ポリシー: 組織または企業に対してカスタムイメージを有効にする必要があります。エンタープライズ所有者は、カスタムイメージへのアクセスを管理し、[アクション] ポリシー設定でアイテム保持ポリシーを設定できます。詳しくは、「企業でGitHub Actionsのポリシーを適用する」をご覧ください。
アクセス許可: カスタムイメージを作成および管理するには、組織またはエンタープライズ所有者であるか、 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 キーワードを含むジョブが正常に実行されるたびに、そのイメージの新しいバージョンが作成されます。

メモ

GitHub では、週単位でスケジュールされたワークフローとしてイメージ生成を構成することをお勧めします。この方法により、依存関係が最新の状態に保たれ、最新のセキュリティパッチが適用されます。詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

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

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

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

文字列構文

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

条件

snapshot キーワードは、スナップショットマッピングに関する if キーワードを使用した条件付き実行をサポートします。条件を使用して、イメージスナップショットを作成するタイミングを制御できます。たとえば、次のジョブは、タグビルドのイメージの作成をスキップします。

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

if キーワードについて詳しくは、「条件を使用してジョブの実行を制御する」をご覧ください。

バージョン管理

カスタムイメージを生成すると、 GitHub によってバージョン番号が自動的に割り当てられ、更新プログラムの管理やイメージ履歴の追跡に役立ちます。

既定の動作

指定した名前のイメージが組織または企業に存在しない場合は、初期バージョン番号 1.0.0 で作成 GitHub 。同じ名前のイメージが既に存在する場合、 GitHub はマイナーバージョン番号 (1.1.0、1.2.0 など) をインクリメントして新しいバージョンを作成します。

YAML ファイルでバージョンを指定しない場合、イメージ生成ではこの既定の動作が使用されます。

ワークフローでのバージョンの指定

YAML マッピングにバージョンを含める場合、 GitHub は最初にメジャーバージョン番号を確認します。

指定したメジャーバージョンが既に存在する場合、新しいイメージでは次のマイナーバージョンが使用されます (たとえば、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

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

カスタムイメージのセキュリティのベストプラクティス

画像に対する不正な変更を防ぐには、次のベストプラクティスに従ってください。

イメージ生成には専用ランナーグループを使用します。 本番環境のイメージを生成するランナーは、専用ランナーグループに所属する必要があります。開発またはテストリポジトリにアクセスできるユーザーは誰でも運用イメージに悪意のあるコードを挿入する可能性があるので、運用リポジトリと開発リポジトリまたはテストリポジトリの間でランナーグループを共有しないでください。
パブリックリポジトリがイメージ生成ランナーにアクセスできないようにします。 イメージ生成ランナーを使用できるリポジトリを、必要なリポジトリのみに制限し、アクセスを定期的に確認します。
リポジトリに最小限の特権を適用します。 イメージ生成ランナーへのアクセス権を持つリポジトリに対して組織全体の write アクセス権を付与することは避けてください。イメージは任意のブランチから生成できるため、書き込みアクセス権を持つすべてのユーザーが任意のコードでブランチを作成し、イメージの生成をトリガーできます。

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

この記事で