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

GitHub ActionsとのGitHub Packagesについて

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

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

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

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

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

Note

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

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

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

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

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

詳細なアクセス許可がサポートされていない GitHub Packages レジストリにアクセスするワークフローが必要な場合GitHub Actions を有効にするときに、GitHub Enterprise Server によってレポジトリに対して自動的に作成される 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 Actions　のワークフロー構文」を参照してください。

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

Note

このワークフローでは、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']

jobs:
# This job checks out the repository contents, installs `npm`, uses npm and webpack to build the app, and uploads the built files as an artifact that can be downloaded later in the workflow.
# It assumes that the built files are written to a directory called `public`.
  run-npm-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: webpack artifacts
          path: public/

# This job uses `npm test` to test the code. `needs: run-npm-build` makes this job dependent on the `run-npm-build` job.
  run-npm-test:
    runs-on: ubuntu-latest
    needs: run-npm-build
    strategy:
      matrix:
        os: [ubuntu-latest]
        node-version: [14.x, 16.x]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - uses: actions/download-artifact@v3
        with:
          name: webpack artifacts
          path: public
      - name: npm install, and test
        run: |
          npm install
          npm test
        env:
          CI: true

# This job publishes the package. `needs: run-npm-test` makes this job dependent on the `run-npm-test` job.
  build-and-push-image:
    runs-on: ubuntu-latest
    needs: run-npm-test 
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write 
      #
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the 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 GitHub Docker Registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # 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 `tags` parameter to tag the image with the SHA of the commit that triggered the workflow.
      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          push: true
          tags: |
            docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}

name: Create and publish a Docker image

on:
  push:
    branches: ['release']
jobs:

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

  run-npm-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: webpack artifacts
          path: public/

This job checks out the repository contents, installs npm, uses npm and webpack to build the app, and uploads the built files as an artifact that can be downloaded later in the workflow. It assumes that the built files are written to a directory called public.

  run-npm-test:
    runs-on: ubuntu-latest
    needs: run-npm-build
    strategy:
      matrix:
        os: [ubuntu-latest]
        node-version: [14.x, 16.x]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - uses: actions/download-artifact@v3
        with:
          name: webpack artifacts
          path: public
      - name: npm install, and test
        run: |
          npm install
          npm test
        env:
          CI: true

This job uses npm test to test the code. needs: run-npm-build makes this job dependent on the run-npm-build job.

  build-and-push-image:
    runs-on: ubuntu-latest
    needs: run-npm-test

This job publishes the package. needs: run-npm-test makes this job dependent on the run-npm-test job.

    permissions:
      contents: read
      packages: write

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

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

      - name: Log in to GitHub Docker Registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

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

      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          push: true
          tags: |
            docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}

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 tags parameter to tag the image with the SHA of the commit that triggered the workflow.

#
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']

jobs:
# This job checks out the repository contents, installs `npm`, uses npm and webpack to build the app, and uploads the built files as an artifact that can be downloaded later in the workflow.
# It assumes that the built files are written to a directory called `public`.
  run-npm-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: webpack artifacts
          path: public/

# This job uses `npm test` to test the code. `needs: run-npm-build` makes this job dependent on the `run-npm-build` job.
  run-npm-test:
    runs-on: ubuntu-latest
    needs: run-npm-build
    strategy:
      matrix:
        os: [ubuntu-latest]
        node-version: [14.x, 16.x]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - uses: actions/download-artifact@v3
        with:
          name: webpack artifacts
          path: public
      - name: npm install, and test
        run: |
          npm install
          npm test
        env:
          CI: true

# This job publishes the package. `needs: run-npm-test` makes this job dependent on the `run-npm-test` job.
  build-and-push-image:
    runs-on: ubuntu-latest
    needs: run-npm-test 
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write 
      #
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the 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 GitHub Docker Registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # 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 `tags` parameter to tag the image with the SHA of the commit that triggered the workflow.
      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          push: true
          tags: |
            docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}

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

ワークフローが完了してから数分後に、新しいパッケージがリポジトリに表示されます。使用可能なパッケージを見つけるには、「パッケージの表示」を参照してください。

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

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

GitHub Actions を通じて GitHub Packages がホストするパッケージをインストールするには、GITHUB_TOKEN を使う際に最小限の設定もしくは追加の認証が必要です。

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 のセキュリティ強化」を参照してください。

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

Note

[Actions のアクセス] メニューオプションを使用してリポジトリをパッケージに追加することは、パッケージをリポジトリに接続することとは別です。詳細については、「パッケージのアクセス制御と可視性の設定」および「リポジトリのパッケージへの接続」を参照してください。
必要に応じて、[ロール] ドロップダウンメニューで、パッケージに対するリポジトリの既定のアクセスレベルを選びます。を使います
ワークフローファイルを開いてください。レジストリへのログインの行で、お使いの 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 ${{ github.actor }} --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 ${{ github.actor }} --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 ${{ github.actor }} --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

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

この記事の内容