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

GitHub ActionsとのGitHub Packagesについて

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

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

コンテナレジストリでの認証

PATはアカウントに対する広汎なアクセスを許可できます。 コンテナレジストリでの認証のためのPATを作成する際には、必要なread:packages、write:packages、delete:packagesスコープだけを選択すべきです。

GitHub Actionsワークフロー内でコンテナレジストリの認証を受けるには、最善のセキュリティと体験のためにGITHUB_TOKENを使ってください。

個人アクセストークンでghcr.ioの認証を受けるワークフローの更新に関するガイダンスとしては、「ghcr.ioにアクセスするワークフローのアップグレード」を参照してください。

ベータの期間にアクションでコンテナレジストリを使いたい場合は、「GitHub Actionsのセキュリティ強化」にあるPATのセキュリティベストプラクティスに従ってください。

認証の例については、「コンテナレジストリ で認証する」を参照してください。

GitHub 上のパッケージレジストリを認証する

GitHub 上の コンテナレジストリ 以外のパッケージレジストリにアクセスするためワークフローを GitHub Packages に対して認証する場合、認証のための個人アクセストークンではなく、GitHub Actions を有効化した際に GitHub がリポジトリに対して自動的に作成する GITHUB_TOKEN を使用することをお勧めします。 contentsスコープに対する読み取りアクセス権と、packagesスコープに対する書き込み権を付与するために、ワークフローファイル中でこのアクセストークンに権限を設定しなければなりません。 フォークでは、 GITHUB_TOKEN には親リポジトリの読み取りアクセス権が付与されます。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。

{{secrets.GITHUB_TOKEN}}コンテキストを使って、ワークフロー中でこのGITHUB_TOKENを参照できます。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。

リポジトリが所有するパッケージに対する権限とパッケージアクセスについて

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

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

コンテナレジストリの権限とパッケージアクセスについて

コンテナレジストリ(ghcr.io)を使うと、ユーザはOrganizationレベルの自立リソースとしてコンテナを作成し、管理できます。 Organizationもしくは個人ユーザアカウントがコンテナを所有でき、それぞれのコンテナへのアクセスはリポジトリ権限とは独立してカスタマイズできます。

コンテナレジストリにアクセスするすべてのワークフローは、個人アクセストークンの代わりにGITHUB_TOKENを使うべきです。 セキュリティのベストプラクティスに関する詳しい情報については「GitHub Actionsのセキュリティ強化」を参照してください。

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

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

たとえばデフォルトでは、ワークフローがGITHUB_TOKENを使ってコンテナを作成するなら:

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

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

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

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

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

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

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

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

  YAML

  name: Create and publish a package
  on:
    push:
      branches: ['release']
  jobs:
    run-npm-build:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
        - name: npm install and build webpack
          run: |
            npm install
            npm run build
        - uses: actions/upload-artifact@main
          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@v2
        - name: Use Node.js ${{ matrix.node-version }}
          uses: actions/setup-node@v1
          with:
            node-version: ${{ matrix.node-version }}
        - uses: actions/download-artifact@main
          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@v2
        - name: Log in to GitHub Docker Registry
          uses: docker/login-action@v1
          with:
            registry: docker.pkg.github.com
            username: ${{ github.actor }}
            password: ${{ secrets.GITHUB_TOKEN }}
        - name: Build container image
          uses: docker/build-push-action@v2
          with:
            push: true
            tags: |
              docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}
              docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.ref }}

  上記に関連する設定については、次の表で説明しています。

  on: push: branches: ['release']	releaseというブランチに変更をプッシュするたびに、Create and publish a packageワークフローを実行するよう設定します。
  run-npm-build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: npm install and build webpack run: | npm install npm run build - uses: actions/upload-artifact@main with: name: webpack artifacts path: public/	このジョブではNPMをインストールし、それをアプリケーションのビルドに使用します。
  run-npm-test: runs-on: ubuntu-latest needs: run-npm-build strategy: matrix: os: [ubuntu-latest] node-version: [14.x] steps: - uses: actions/checkout@v2 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v1 with: node-version: ${{ matrix.node-version }} - uses: actions/download-artifact@main with: name: webpack artifacts path: public - name: npm install, and test run: | npm install npm test env: CI: true	このジョブではnpm testを使用してコードをテストします。 needs: run-npm-buildコマンドにより、このジョブをrun-npm-buildジョブに依存するようにします。
  build-and-push-image: runs-on: ubuntu-latest needs: run-npm-test	このジョブはパッケージを公開します。 needs: run-npm-testコマンドにより、このジョブをrun-npm-testジョブに依存するようにします。
  permissions: contents: read packages: write	GITHUB_TOKENに付与されている権限をこのジョブ中のアクションに設定します。
  - name: Log in to GitHub Docker Registry uses: docker/login-action@v1 with: registry: docker.pkg.github.com username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }}	パッケージを公開するアカウントとパスワードを使ってレジストリにログインするLog in to GitHub Docker Registryという新しいステップを作成します。 いったん公開されると、パッケージはここで定めたアカウントが所有することになります。
  - name: Build container image	Build container imageという新しいステップを作成します。 このステップは、build-and-push-imageジョブの一部として実行されます。
  uses: docker/build-push-action@v2	Dockerのbuild-push-actionアクションを使用して、リポジトリのDockerfileを元にイメージをビルドします。 ビルドが成功すると、イメージをGitHub Packagesにプッシュします。
  with:	必要なパラメータをbuild-push-actionアクションに送信します。 これは以降の行で定義されます。
  push: true	ビルドに成功したら、このイメージをレジストリにプッシュします。
  tags: | docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }} docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.ref }}	コミットSHAとgit ref（たとえばこのパッケージを作成するのに使われたブランチの名前）で、公開されたパッケージにタグ付けします。

  • この新しいワークフローは、リポジトリのreleaseという名前のブランチに変更をプッシュするたびに自動的に実行されます。 [Actions] タブで、この進捗を表示できます。
  • ワークフローが完成すると、その数分後にリポジトリで新しいパッケージが表示されます。 使用可能なパッケージを見つけるには、「リポジトリのパッケージを表示する」を参照してください。

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

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

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

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

  ghcr.ioにアクセスするワークフローのアップグレード

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

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

  2. ひだりのサイドバーでActions access（Actionsのアクセス）をクリックしてください。

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

     ノート: Actionsのアクセスメニューオプションを通じてリポジトリをコンテナに追加することは、コンテナをリポジトリに接続することとは異なります。 詳しい情報については「パッケージへのワークフローアクセスの保証」及び「リポジトリのパッケージへの接続」を参照してください。

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

  5. ワークフローファイルを開いてください。 ghcr.ioへのログインの行で、PATを${{ secrets.GITHUB_TOKEN }}に置き換えてください。

  たとえば、このワークフローは ${{ secrets.GITHUB_TOKEN }}を認証に使ってDockerコンテナを公開します。

  YAML

  name: Demo Push
  
  on:   
    push:
      # `master`をDockerの`latest`イメージとして公開。.
      branches:
        - master
        - seed
  
      # `v1.2.3`タグをリリースとして公開。
      tags:
        - v*
  
    # 任意のPRに対してテストを実行。.
    pull_request:
  
  env:
    IMAGE_NAME: ghtoken_product_demo
  
  jobs:
    # GitHub Packagesにイメージをプッシュ。
    # https://docs.docker.com/docker-hub/builds/ も参照
    push:
      runs-on: ubuntu-latest
      permissions:
        packages: write
        contents: read
  
      steps:
        - uses: actions/checkout@v2
  
        - name: Build image
          run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"
  
        - name: Log into registry
          # ここでPATをGITHUB_TOKENに更新
          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]')
            # git refのプレフィックスをバージョンから除去
            VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
            # "v"プレフィックスをタグ名から除去
            [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
            # Dockerの`latest`タグ記法を使用
            [ "$VERSION" == "master" ] && VERSION=latest
            echo IMAGE_ID=$IMAGE_ID
            echo VERSION=$VERSION
            docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
            docker push $IMAGE_ID:$VERSION