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

GitHub ActionsとのGitHub Packagesについて

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

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

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

一部の GitHub Packages レジストリでは、細かなアクセス許可がサポートされています。 つまり、パッケージをユーザーまたは組織が所有できるよう、あるいはリポジトリにリンクできるように選べます。 細かなアクセス許可をサポートするレジストリの一覧については、「GitHub Packages のアクセス許可について」を参照してください。

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

GITHUB_TOKEN の詳細については「ワークフローで認証する」を参照してください。 アクションでレジストリを使用するときのベスト プラクティスについては、「GitHub Actions のセキュリティ強化」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

ワークフローを通じて変更されたコンテナに対するデフォルトの権限及びアクセス設定

ワークフローを通じてコンテナを作成、インストール、変更、削除する場合、管理者がワークフローに確実にアクセスできるようにするために使われるデフォルトの権限及びアクセス設定があります。 これらのアクセス設定も調整できます。

たとえば既定では、ワークフローで GITHUB_TOKEN を使用してコンテナーが作成された場合:

• コンテナはワークフローが実行されたリポジトリの可視性と権限モデルを継承します。
• ワークフローが実行されたリポジトリの管理者は、コンテナが作成されるとそのコンテナの管理者になります。

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

コンテナへのアクセスをもっと詳細に調整したり、デフォルトの権限動作の一部を調整したりすることもできます。 詳しくは、「パッケージのアクセス制御と可視性の設定」を参照してください。

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

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

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

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

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

# <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>このワークフローはGitHubによって認定されていないアクションを使用します。
# <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>それらはサードパーティによって提供され、
# <a name="separate-terms-of-service-privacy-policy-and-support"></a>別個の利用規約、プライバシーポリシー、
# <a name="documentation"></a>ドキュメントを参照してください。

# <a name="github-recommends-pinning-actions-to-a-commit-sha"></a>GitHub では、コミット SHA にアクションをピン留めすることが推奨されます。
# <a name="to-get-a-newer-version-you-will-need-to-update-the-sha"></a>新しいバージョンを取得するには、SHA を更新する必要があります。
# <a name="you-can-also-reference-a-tag-or-branch-but-the-action-may-change-without-warning"></a>タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。

name: Create and publish a Docker image

on:
  push:
    branches: ['release']

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

  run-npm-test:
    runs-on: ubuntu-latest
    needs: run-npm-build
    strategy:
      matrix:
        os: [ubuntu-latest]
        node-version: [12.x, 14.x]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        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

  build-and-push-image:
    runs-on: ubuntu-latest
    needs: run-npm-test 
    permissions: 
      contents: read
      packages: write 
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Log in to GitHub Docker Registry
        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push Docker image
        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
        with:
          push: true
          tags: |
            docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}

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

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

run-npm-test:
  runs-on: ubuntu-latest
  needs: run-npm-build
  strategy:
    matrix:
      os: [ubuntu-latest]
      node-version: [12.x, 14.x]
  steps:
    - uses: actions/checkout@v3
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      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

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

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

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

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

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

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

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

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

GITHUB_TOKEN の詳細については「ワークフローで認証する」を参照してください。

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

1. パッケージのランディングページにアクセスしてください。

2. 左側のサイドバーで、 [アクションのアクセス] をクリックします。

3. コンテナパッケージがワークフローに確実にアクセスできるようにするためには、ワークフローが保存されているリポジトリをコンテナに追加しなければなりません。 [リポジトリの追加] をクリックして、追加するリポジトリを検索します。

   注: [アクションのアクセス] メニュー オプションを使用してコンテナーにリポジトリを追加する操作は、コンテナーをリポジトリに接続する操作とは異なります。 詳細については、「パッケージへのワークフローのアクセスの確保」と「リポジトリのパッケージへの接続」を参照してください。

4. あるいは"role（ロール）"ドロップダウンメニューを使い、コンテナイメージに対してリポジトリに持たせたいデフォルトのアクセスレベルを選択してください。

5. ワークフローファイルを開いてください。 レジストリへのログインの行で、お使いの personal access token を ${{ secrets.GITHUB_TOKEN }} に置き換えてください。

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

name: Demo Push

on:   
  push:
    # Publish `master` as Docker `latest` image.
    branches:
      - master
      - seed

    # Publish `v1.2.3` tags as releases.
    tags:
      - v*

  # Run tests for any PRs.
  pull_request:

env:
  IMAGE_NAME: ghtoken_product_demo

jobs:
  # Push image to GitHub Packages.
  # See also https://docs.docker.com/docker-hub/builds/
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read

    steps:
      - uses: actions/checkout@v3

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

      - name: Log in to registry
        # This is where you will update the personal access token to GITHUB_TOKEN
        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

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