Publishing and installing a package with GitHub Actions

About GitHub Packages with GitHub Actions

GitHub Actions help you automate your software development workflows in the same place you store code and collaborate on pull requests and issues. You can write individual tasks, called actions, and combine them to create a custom workflow. With GitHub Actions you can build end-to-end continuous integration (CI) and continuous deployment (CD) capabilities directly in your repository. For more information, see "About GitHub Actions."

You can extend the CI and CD capabilities of your repository by publishing or installing packages as part of your workflow.

Authenticating to the Container registry

To authenticate to the Container registry within a GitHub Actions workflow, use the GITHUB_TOKEN for the best security and experience. If your workflow is using a personal access token (PAT) to authenticate to ghcr.io, then we highly recommend you update your workflow to use the GITHUB_TOKEN.

For guidance on updating your workflows that authenticate to ghcr.io with a personal access token, see "Upgrading a workflow that accesses ghcr.io."

For more information about the GITHUB_TOKEN, see "Authentication in a workflow."

If you're using the Container registry in actions, follow our security best practices at "Security hardening for GitHub Actions."

Authenticating to package registries on GitHub

If you want your workflow to authenticate to GitHub Packages to access a package registry other than the Container registry on GitHub.com, then we recommend using the GITHUB_TOKEN that GitHub automatically creates for your repository when you enable GitHub Actions instead of a personal access token for authentication. You should set the permissions for this access token in the workflow file to grant read access for the contents scope and write access for the packages scope. For forks, the GITHUB_TOKEN is granted read access for the parent repository. For more information, see "Authenticating with the GITHUB_TOKEN."

You can reference the GITHUB_TOKEN in your workflow file using the {{secrets.GITHUB_TOKEN}} context. For more information, see "Authenticating with the GITHUB_TOKEN."

About permissions and package access for repository-owned packages

When you enable GitHub Actions, GitHub installs a GitHub App on your repository. The GITHUB_TOKEN secret is a GitHub App installation access token. You can use the installation access token to authenticate on behalf of the GitHub App installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see "Permissions for the GITHUB_TOKEN."

GitHub Packages allows you to push and pull packages through the GITHUB_TOKEN available to a GitHub Actions workflow.

About permissions and package access for Container registry

The Container registry (ghcr.io) allows users to create and administer containers as free-standing resources at the organization level. Containers can be owned by an organization or personal user account and you can customize access to each of your containers separately from repository permissions.

All workflows accessing the Container registry should use the GITHUB_TOKEN instead of a personal access token. For more information about security best practices, see "Security hardening for GitHub Actions."

Default permissions and access settings for containers modified through workflows

When you create, install, modify, or delete a container through a workflow, there are some default permission and access settings used to ensure admins have access to the workflow. You can adjust these access settings as well.

For example, by default if a workflow creates a container using the GITHUB_TOKEN, then:

• The container inherits the visibility and permissions model of the repository where the workflow is run.
• Repository admins where the workflow is run become the admins of the container once the container is created.

These are more examples of how default permissions work for workflows that manage packages.

You can also adjust access to containers in a more granular way or adjust some of the default permissions behavior. For more information, see "Configuring a package’s access control and visibility."

Publishing a package using an action

You can use GitHub Actions to automatically publish packages as part of your continuous integration (CI) flow. This approach to continuous deployment (CD) allows you to automate the creation of new package versions, if the code meets your quality standards. For example, you could create a workflow that runs CI tests every time a developer pushes code to a particular branch. If the tests pass, the workflow can publish a new package version to GitHub Packages.

Configuration steps vary by package client. For general information about configuring a workflow for GitHub Actions, see "Configuring a workflow."

The following example demonstrates how you can use GitHub Actions to build your app, and then automatically create a Docker image and publish it to GitHub Packages.

Create a new workflow file in your repository (such as .github/workflows/deploy-image.yml), and add the following YAML:

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

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@v2

      - 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 }}

The relevant settings are explained in the following table. For full details about each element in a workflow, see "Workflow syntax for GitHub Actions."

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 

- 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 }}

This new workflow will run automatically every time you push a change to a branch named release in the repository. You can view the progress in the Actions tab.

A few minutes after the workflow has completed, the new package will visible in your repository. To find your available packages, see "Viewing a repository's packages."

Installing a package using an action

You can install packages as part of your CI flow using GitHub Actions. For example, you could configure a workflow so that anytime a developer pushes code to a pull request, the workflow resolves dependencies by downloading and installing packages hosted by GitHub Packages. Then, the workflow can run CI tests that require the dependencies.

Installing packages hosted by GitHub Packages through GitHub Actions requires minimal configuration or additional authentication when you use the GITHUB_TOKEN. Data transfer is also free when an action installs a package. For more information, see "About billing for GitHub Packages."

Configuration steps vary by package client. For general information about configuring a workflow for GitHub Actions, see "Configuring a workflow."

Upgrading a workflow that accesses ghcr.io

The Container registry supports the GITHUB_TOKEN for easy and secure authentication in your workflows. If your workflow is using a personal access token (PAT) to authenticate to ghcr.io, then we highly recommend you update your workflow to use the GITHUB_TOKEN.

For more information about the GITHUB_TOKEN, see "Authentication in a workflow."

Using the GITHUB_TOKEN instead of a PAT, which includes the repo scope, increases the security of your repository as you don't need to use a long-lived PAT that offers unnecessary access to the repository where your workflow is run. For more information about security best practices, see "Security hardening for GitHub Actions."

1. Navigate to your package landing page.

2. In the left sidebar, click Actions access.

3. To ensure your container package has access to your workflow, you must add the repository where the workflow is stored to your container. Click Add repository and search for the repository you want to add.

   Note: Adding a repository to your container through the Actions access menu option is different than connecting your container to a repository. For more information, see "Ensuring workflow access to your package" and "Connecting a repository to a package."

4. Optionally, using the "role" drop-down menu, select the default access level that you'd like the repository to have to your container image.

5. Open your workflow file. On the line where you log in to ghcr.io, replace your PAT with ${{ secrets.GITHUB_TOKEN }}.

For example, this workflow publishes a Docker image using ${{ secrets.GITHUB_TOKEN }} to authenticate.

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@v2

      - 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 PAT to 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

          # 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