GitHub Actionsでのパッケージの公開とインストール

GitHub ActionsとのGitHub Packagesについて

GitHub Actionsは、コードを保存するのと同じ場所でソフトウェア開発のワークフローを自動化し、プルリクエストやIssueで協力することを支援します。個々のタスクを書き、アクションを呼び出し、それらを組み合わせてカスタムのワークフローを作成できます。 GitHub Actions では、エンドツーエンドの継続的インテグレーション (CI) と継続的デプロイメント (CD) 機能をリポジトリに直接ビルドすることができます。詳しくは、「GitHub Actions について」をご覧ください。

ワークフローの一部としてパッケージの公開やインストールを行うことで、リポジトリのCI及びCDの機能を拡張できます。

詳細なアクセス許可を持つパッケージレジストリに対する認証

一部の GitHub Packages レジストリでは、細かなアクセス許可がサポートされています。つまり、パッケージをユーザーまたは Organization にスコープ設定するか、リポジトリにリンクするのを許可することを選べます。詳細なアクセス許可をサポートするレジストリの一覧については、「GitHub Packagesの権限について」をご覧ください。

細かなアクセス許可をサポートするレジストリについては、GitHub Actions ワークフローで personal access token を使ってレジストリの認証を受ける場合は GITHUB_TOKEN を使うようにワークフローを更新することを強くお勧めします。 personal access token を使ってレジストリに対する認証を行うワークフローの更新に関するガイダンスについては、「GitHub Actionsでのパッケージの公開とインストール」をご覧ください。

注: GitHub Actions ワークフローで REST API を使用してパッケージを削除および復元する機能は、現在パブリックベータ版であり、変更される可能性があります。

トークンにパッケージに対する admin アクセス許可がある場合、GitHub Actions ワークフローで GITHUB_TOKEN と REST API を使って、パッケージを削除または復元できます。ワークフローを使ってパッケージを発行するリポジトリと、パッケージに明示的に接続したリポジトリには、リポジトリ内のパッケージに対する admin アクセス許可が自動的に付与されます。

GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。アクションでレジストリを使うときのベストプラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

リポジトリがスコープ指定されたアクセス許可を持つパッケージレジストリに対する認証

一部の GitHub Packages レジストリでは、リポジトリがスコープ指定されたアクセス許可のみがサポートされ、詳細なアクセス許可はサポートされていません。これらのレジストリの一覧については、「GitHub Packagesの権限について」をご覧ください。

詳細なアクセス許可がサポートされていない GitHub Packages レジストリにアクセスするワークフローが必要な場合GitHub Actions を有効にするときに、GitHub によってレポジトリに対して自動的に作成される GITHUB_TOKEN を使うことをお勧めします。ワークフローファイルでこのアクセストークンにアクセス許可を設定して、contents スコープに対する読み取りアクセス権と、packages スコープに対する書き込みアクセス権を付与する必要があります。フォークの場合、GITHUB_TOKEN には親リポジトリの読み取りアクセス権が付与されます。詳しくは、「自動トークン認証」を参照してください。

ワークフローファイル内の GITHUB_TOKEN は、{{secrets.GITHUB_TOKEN}} コンテキストを使って参照できます。詳しくは、「自動トークン認証」を参照してください。

アクセス許可とパッケージのアクセスについて

ユーザーまたは Organization にスコープ指定されたパッケージ

詳細なアクセス許可をサポートするレジストリを使うと、ユーザーは Organization レベルで独立したリソースとしてパッケージを作成および管理できます。 Organization または個人アカウントにパッケージのスコープを設定でき、リポジトリのアクセス許可とは別に各パッケージへのアクセス権をカスタマイズできます。

詳細なアクセス許可をサポートするレジストリにアクセスするすべてのワークフローで、personal access token の代わりに GITHUB_TOKEN を使う必要があります。セキュリティのベストプラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

リポジトリにスコープ指定されたパッケージ

GitHub Actionsを有効化すると、GitHubはリポジトリにGitHub Appをインストールします。 GITHUB_TOKEN シークレットは、GitHub App インストールアクセストークンです。このインストールアクセストークンは、リポジトリにインストールされたGitHub Appの代わりに認証を受けるために使うことができます。このトークンの権限は、ワークフローを含むリポジトリに限定されます。詳しくは、「自動トークン認証」を参照してください。

GitHub Packages を使用すると、GitHub Actions ワークフローで利用できる GITHUB_TOKEN を通じてパッケージをプッシュしたりプルしたりできます。

ワークフローを通じて変更されるパッケージの既定のアクセス許可とアクセス設定

詳細なアクセス許可をサポートしているレジストリ内のパッケージの場合、ワークフローを通じてパッケージを作成、インストール、変更、削除するときに、管理者がワークフローに確実にアクセスできるようにするために使われる既定のアクセス許可とアクセス設定がいくつかあります。これらのアクセス設定も調整できます。詳細なアクセス許可をサポートするレジストリの一覧については、「GitHub Packagesの権限について」をご覧ください。

たとえば、ワークフローで GITHUB_TOKEN を使ってパッケージを作成する場合は、既定では次のようになります。

パッケージは、ワークフローが実行されたリポジトリの可視性とアクセス許可モデルを継承します。
パッケージが作成されると、ワークフローが実行されたリポジトリの管理者が、そのパッケージの管理者になります。

パッケージを管理するワークフローに対してデフォルトの権限の働き方の例は、もっとあります。

GitHub Actionsワークフロータスク	既定のアクセス許可とアクセス
既存のものをダウンロードする	- パッケージがパブリックの場合は、任意のリポジトリで実行された任意のワークフローが、パッケージをダウンロードできます。 - パッケージが内部の場合は、Enterprise アカウントによって所有される任意のリポジトリで実行されたすべてのワークフローが、パッケージをダウンロードできます。エンタープライズが所有する組織の場合は、エンタープライズ内の任意のリポジトリを読み取ることができる - パッケージがプライベートの場合は、リポジトリ内で実行されたワークフローのうち、そのパッケージに対する読み取りアクセス許可を付与されているものだけが、パッケージをダウンロードできます。
新しいバージョンを既存のパッケージにアップロードする	- パッケージがプライベート、内部、またはパブリックの場合、リポジトリ内で実行されたワークフローのうち、そのパッケージに対する書き込みアクセス許可を付与されているものだけが、パッケージに新しいバージョンアップロードできます。
パッケージまたはパッケージのバージョンを削除する	- パッケージがプライベート、内部、またはパブリックの場合、リポジトリ内で実行されたワークフローのうち、管理者アクセス許可を付与されているものだけが、パッケージの既存のバージョンを削除できます。

パッケージへのアクセス権をさらに細かく調整したり、既定のアクセス許可の動作の一部を調整したりすることもできます。詳しくは、「パッケージのアクセス制御と可視性の設定」を参照してください。

アクションを使ったパッケージの公開

継続的インテグレーション (CI) フローの一環として、GitHub Actionsを使用してパッケージを自動的に公開できます。この継続的デプロイメント (CD) に対するアプローチにより、コードが品質基準を満たしている場合に新しいパッケージの作成を自動化できます。たとえば、開発者が特定のブランチにプッシュするたびに CI テストを実行するワークフローを作成してはいかがでしょう。テストにパスすると、このワークフローは新しいパッケージバージョンをGitHub Packagesに公開できます。

パッケージのクライアントによって、設定のステップは様々です。 GitHub Actions のワークフローの構成に関する一般的な情報については、「ワークフローの使用」を参照してください。

以下の例では、GitHub Actionsを使用してアプリケーションのビルドを行い、それから自動的にDockerイメージを作成してGitHub Packagesに公開する方法を示しています。

リポジトリに新しいワークフローファイル (.github/workflows/deploy-image.yml など) を作成し、以下の YAML を追加します。

YAML

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

# GitHub では、コミット SHA にアクションをピン留めすることが推奨されます。
# 新しいバージョンを取得するには、SHA を更新する必要があります。
# タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。

name: Create and publish a Docker image

on:
 push:
   branches: ['release']

env:
 REGISTRY: ghcr.io
 IMAGE_NAME: ${{ github.repository }}

jobs:
 build-and-push-image:
   runs-on: ubuntu-latest
   permissions:
     contents: read
     packages: write

   steps:
     - name: Checkout repository
       uses: actions/checkout@v3

     - name: Log in to the Container registry
       uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
       with:
         registry: ${{ env.REGISTRY }}
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}

     - name: Extract metadata (tags, labels) for Docker
       id: meta
       uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
       with:
         images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

     - name: Build and push Docker image
       uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
       with:
         context: .
         push: true
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}

上記に関連する設定については、次の表で説明しています。ワークフロー内の各要素について詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。

```yaml on: push: branches: ['release'] ```	`release` というブランチに変更をプッシュするたびに、`Create and publish a Docker image` ワークフローを実行するよう設定します。
`env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }}`	ワークフローに2つのカスタムの環境変数を定義します。これらはContainer registryドメイン、そしてこのワークフローがビルドするDockerイメージの名前として使われます。
`jobs: build-and-push-image: runs-on: ubuntu-latest`	このワークフロー中には1つのジョブがあります。これは、Ubuntuの利用可能な最新バージョンで実行されるよう設定されています。
```yaml permissions: contents: read packages: write ```	`GITHUB_TOKEN` に付与されているアクセス許可をこのジョブ内のアクション用に設定します。
```yaml - name: Log in to the Container registry uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} ```	パッケージを公開するアカウントとパスワードを使ってレジストリにログインする `Log in to the Container registry` というステップを作成します。いったん公開されると、パッケージはここで定義されているアカウントにスコープ設定されます。
```yaml - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} ```	このステップは `docker/metadata-action` を使って、指定されたイメージに適用されるタグとラベルを抽出します。 `id` "meta"は、このステップの出力が以降のステップから参照できるようにします。 `images` の値は、タグとラベルのためのベース名を提供します。
```yaml - name: Build and push Docker image ```	`Build and push Docker image` という新しいステップを作成します。このステップは、`build-and-push-image` ジョブの一部として実行されます。
```yaml uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc ```	Docker の `build-push-action` アクションを使用して、リポジトリの `Dockerfile` を元にイメージをビルドします。ビルドが成功すると、イメージをGitHub Packagesにプッシュします。
```yaml with: ```	必要なパラメーターを `build-push-action` アクションに送信します。これらは以降の行で定義されます。
```yaml context: . ```	ビルドのコンテキストを、指定されたパス内にあるファイル群として定義します。詳細については、「使用」を参照してください。
```yaml push: true ```	ビルドに成功したら、このイメージをレジストリにプッシュします。
`tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }}`	"meta"ステップで抽出されたタグとラベルを追加します。

この新しいワークフローは、リポジトリの release という名前のブランチに変更をプッシュするたびに自動的に実行されます。 [アクション] タブで、この進捗を表示できます。

ワークフローが完成すると、その数分後にリポジトリで新しいパッケージが表示されます。使用可能なパッケージを見つけるには、「パッケージの表示」をご覧ください。

アクションを使ったパッケージのインストール

GitHub Actionsを使い、CIフローの一部としてパッケージをインストールできます。たとえば、開発者がコードをプルリクエストにプッシュすると、いつでもワークフローがGitHub Packagesによってホストされているパッケージをダウンロードしてインストールすることで、依存関係を解決するようにワークフローを設定できます。そして、ワークフローはその依存関係を必要とするCIテストを実行できます。

GitHub Actions を通じて GitHub Packages がホストするパッケージをインストールするには、GITHUB_TOKEN を使う際に最小限の設定もしくは追加の認証が必要です。アクションがパッケージをインストールする場合、データ転送も無料です。詳細については、「GitHubパッケージの支払いについて」を参照してください。

パッケージのクライアントによって、設定のステップは様々です。 GitHub Actions のワークフローの構成に関する一般的な情報については、「ワークフローの使用」を参照してください。

personal access token を使ってレジストリにアクセスするワークフローのアップグレード

GitHub Packages は、ワークフロー内での容易でセキュリティで保護された認証のために GITHUB_TOKEN をサポートしています。詳細なアクセス許可をサポートするレジストリを使っており、お使いのワークフローで personal access token を使ってレジストリの認証を受ける場合、GITHUB_TOKEN を使うようにワークフローを更新することを強くお勧めします。

GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。

personal access token (classic) の代わりに repo スコープを含む GITHUB_TOKEN を使えば、ワークフローが実行されるリポジトリへの不要なアクセスを提供する長期間有効な personal access token を使う必要がなくなるので、リポジトリのセキュリティが向上します。セキュリティのベストプラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

パッケージのランディングページにアクセスしてください。
パッケージがワークフローに確実にアクセスできるようにするには、ワークフローが格納されているリポジトリをパッケージに追加する必要があります。 [Actions のアクセスの管理] で、 [リポジトリの追加] をクリックして、追加するリポジトリを検索します。

注: パッケージの設定の [Actions のアクセスの管理] の [リポジトリの追加] ボタンを使用してリポジトリをパッケージに追加することは、パッケージをリポジトリに接続することとは別です。詳細については、「パッケージのアクセス制御と可視性の設定」および「リポジトリのパッケージへの接続」を参照してください。
必要に応じて、[ロール] ドロップダウンメニューで、パッケージに対するリポジトリの既定のアクセスレベルを選びます。を使います
ワークフローファイルを開いてください。レジストリへのログインの行で、お使いの personal access token を ${{ secrets.GITHUB_TOKEN }} に置き換えてください。

たとえば、このワークフローでは、Docker イメージを Container registry に公開し、${{ secrets.GITHUB_TOKEN }} を使って認証します。