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 を追加します。

注:

このワークフローでは、GitHub によって認定されていないアクションが使われます。それらはサードパーティによって提供され、個別のサービス使用条件、プライバシーポリシー、およびサポートドキュメントが適用されます。
GitHub では、コミット SHA にアクションをピン留めすることをお勧めします。新しいバージョンを取得するには、SHA を更新する必要があります。タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。

YAML

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['release']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      # 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

name: Create and publish a Docker image

on:
  push:
    branches: ['release']

Configures this workflow to run every time a change is pushed to the branch called release.

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

Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest

There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.

    permissions:
      contents: read
      packages: write

Sets the permissions granted to the GITHUB_TOKEN for the actions in this job.

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

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

Uses the docker/login-action action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.

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

This step uses docker/metadata-action to extract tags and labels that will be applied to the specified image. The id "meta" allows the output of this step to be referenced in a subsequent step. The images value provides the base name for the tags and labels.

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

This step uses the docker/build-push-action action to build the image, based on your repository's Dockerfile. If the build succeeds, it pushes the image to GitHub Packages. It uses the context parameter to define the build's context as the set of files located in the specified path. For more information, see "Usage" in the README of the docker/build-push-action repository. It uses the tags and labels parameters to tag and label the image with the output from the "meta" step.

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['release']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      # 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

この新しいワークフローは、リポジトリの 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 のアクセスの管理] の [リポジトリの追加] ボタンを使用してリポジトリをパッケージに追加することは、パッケージをリポジトリに接続することとは別です。詳細については、「パッケージのアクセス制御と可視性の設定」および「リポジトリのパッケージへの接続」を参照してください。

1. 必要に応じて、**[ロール]** ドロップダウンメニューで、パッケージに対するリポジトリの既定のアクセスレベルを選びます。を使います 1. ワークフローファイルを開いてください。レジストリへのログインの行で、お使いの personal access token を `${{ secrets.GITHUB_TOKEN }}` に置き換えてください。

たとえば、このワークフローでは、Docker イメージを Container registry に公開し、${{ secrets.GITHUB_TOKEN }} を使って認証します。詳しくは、Docker ドキュメントの自動ビルドの設定に関する説明をご覧ください。

YAML

#
name: Demo Push

# This workflow runs when any of the following occur:
# - A push is made to a branch called `main` or `seed`
# - A tag starting with "v" is created
# - A pull request is created or updated
on:
  push:
    branches:
      - main
      - seed
    tags:
      - v*
  pull_request:
  # This creates an environment variable called `IMAGE_NAME ` with the value `ghtoken_product_demo`.
env:
  IMAGE_NAME: ghtoken_product_demo
#
jobs:
  # This pushes the image to GitHub Packages.
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      #
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"

      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin
        #
      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          # This changes all uppercase characters to lowercase.
          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
          # This strips the git ref prefix from the version.
          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
          # This strips the "v" prefix from the tag name.
          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # This uses the Docker `latest` tag convention.
          [ "$VERSION" == "main" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION

name: Demo Push

on:
  push:
    branches:
      - main
      - seed
    tags:
      - v*
  pull_request:

This workflow runs when any of the following occur:

A push is made to a branch called main or seed
A tag starting with "v" is created
A pull request is created or updated

env:
  IMAGE_NAME: ghtoken_product_demo

This creates an environment variable called IMAGE_NAME with the value ghtoken_product_demo.

jobs:

  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read

This pushes the image to GitHub Packages.

    steps:
      - uses: actions/checkout@v4
      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"
      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin

      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')

This changes all uppercase characters to lowercase.

          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')

This strips the git ref prefix from the version.

          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')

This strips the "v" prefix from the tag name.

          [ "$VERSION" == "main" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION

This uses the Docker latest tag convention.

#
name: Demo Push

# This workflow runs when any of the following occur:
# - A push is made to a branch called `main` or `seed`
# - A tag starting with "v" is created
# - A pull request is created or updated
on:
  push:
    branches:
      - main
      - seed
    tags:
      - v*
  pull_request:
  # This creates an environment variable called `IMAGE_NAME ` with the value `ghtoken_product_demo`.
env:
  IMAGE_NAME: ghtoken_product_demo
#
jobs:
  # This pushes the image to GitHub Packages.
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      #
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"

      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin
        #
      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          # This changes all uppercase characters to lowercase.
          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
          # This strips the git ref prefix from the version.
          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
          # This strips the "v" prefix from the tag name.
          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # This uses the Docker `latest` tag convention.
          [ "$VERSION" == "main" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION