docs/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md

title, intro, product, redirect_from, versions

title	intro	product	redirect_from	versions
Publishing and installing a package with GitHub Actions	You can configure a workflow in {% data variables.product.prodname_actions %} to automatically publish or install a package from {% data variables.product.prodname_registry %}.	{% data reusables.gated-features.packages %}	/github/managing-packages-with-github-packages/using-github-packages-with-github-actions /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions /packages/guides/using-github-packages-with-github-actions	free-pro-team enterprise-server github-ae * >=2.22 *

{% data reusables.package_registry.packages-ghes-release-stage %} {% data reusables.package_registry.packages-ghae-release-stage %} {% data reusables.actions.ae-beta %} {% data reusables.actions.ae-self-hosted-runners-notice %}

About {% data variables.product.prodname_registry %} with {% data variables.product.prodname_actions %}

{% data reusables.repositories.about-github-actions %} {% data reusables.repositories.actions-ci-cd %} For more information, see "About {% data variables.product.prodname_actions %}."

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

{% if currentVersion == "free-pro-team@latest" %}

Authenticating to the {% data variables.product.prodname_container_registry %}

{% data reusables.package_registry.container-registry-beta %}

{% data reusables.package_registry.authenticate_with_pat_for_container_registry %}

For an authentication example, see "Authenticating with the {% data variables.product.prodname_container_registry %}."

{% endif %}

Authenticating to package registries on {% data variables.product.prodname_dotcom %}

{% if currentVersion == "free-pro-team@latest" %}If you want your workflow to authenticate to {% data variables.product.prodname_registry %} to access a package registry other than the {% data variables.product.prodname_container_registry %} on {% data variables.product.product_name %}, then{% else %}To authenticate to package registries on {% data variables.product.product_name %},{% endif %} we recommend using the GITHUB_TOKEN that {% data variables.product.product_name %} automatically creates for your repository when you enable {% data variables.product.prodname_actions %} instead of a personal access token for authentication. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %}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. {% else %}It has read and write permissions for packages in the repository where the workflow runs. {% endif %}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 {% raw %}{{secrets.GITHUB_TOKEN}}{% endraw %} context. For more information, see "Authenticating with the GITHUB_TOKEN."

About permissions and package access for repository-owned packages

{% note %}

Note: Repository-owned packages include RubyGems, npm, Apache Maven, NuGet, Gradle, and Docker packages that use the package namespace docker.pkg.github.com.

{% endnote %}

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."

{% data variables.product.prodname_registry %} allows you to push and pull packages through the GITHUB_TOKEN available to a {% data variables.product.prodname_actions %} workflow.

{% if currentVersion == "free-pro-team@latest" %}

About permissions and package access for {% data variables.product.prodname_container_registry %}

The {% data variables.product.prodname_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 {% data variables.product.prodname_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.

{% data variables.product.prodname_actions %} workflow task	Default permissions and access
Download an existing container	- If the container is public, any workflow running in any repository can download the container. - If the container is internal, then all workflows running in any repository owned by the Enterprise account can download the container. For enterprise-owned organizations, you can read any repository in the enterprise - If the container is private, only workflows running in repositories that are given read permission on that container can download the container.
Upload a new version to an existing container	- If the container is private, internal, or public, only workflows running in repositories that are given write permission on that container can upload new versions to the container.
Delete a container or versions of a container	- If the container is private, internal, or public, only workflows running in repositories that are given delete permission can delete existing versions of the container.

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."

{% endif %}

Publishing a package using an action

You can use {% data variables.product.prodname_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 {% data variables.product.prodname_registry %}.

{% data reusables.package_registry.actions-configuration %}

The following example demonstrates how you can use {% data variables.product.prodname_actions %} to build and test your app, and then automatically create a Docker image and publish it to {% data variables.product.prodname_registry %}:

• Create a new workflow file in your repository (such as .github/workflows/deploy-image.yml), and add the following 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: {% raw %}
        - uses: actions/checkout@v2
        - name: Use Node.js ${{ matrix.node-version }}
          uses: actions/setup-node@v1
          with:
            node-version: ${{ matrix.node-version }}{% endraw %}
        - 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 {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %}
      permissions: 
        contents: read
        packages: write {% endif %}
      steps:
        - name: Checkout
          uses: actions/checkout@v2
        - name: Log in to GitHub Docker Registry
          uses: docker/login-action@v1
          with:
            registry: {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}
            username: {% raw %}${{ github.actor }}{% endraw %}
            password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
        - name: Build container image
          uses: docker/build-push-action@v2
          with:
            push: true
            tags: |
              {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.sha }}{% endraw %}
              {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.ref }}{% endraw %}
  

  The relevant settings are explained in the following table:

  {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %}

  {% endif %}

  {% raw %} on: push: branches: ['release'] {% endraw %}	Configures the Create and publish a package workflow to run every time a change is pushed to the branch called release.
  {% raw %} 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/ {% endraw %}	This job installs NPM and uses it to build the app.
  {% raw %} 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 {% endraw %}	This job uses npm test to test the code. The needs: run-npm-build command makes this job dependent on the run-npm-build job.
  {% raw %} build-and-push-image: runs-on: ubuntu-latest needs: run-npm-test {% endraw %}	This job publishes the package. The needs: run-npm-test command makes this job dependent on the run-npm-test job.
  {% raw %} permissions: contents: read packages: write {% endraw %}	Sets the permissions granted to the GITHUB_TOKEN for the actions in this job.
  {% raw %} - name: Log in to GitHub Docker Registry uses: docker/login-action@v1 with: registry: {% endraw %}{% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} {% endraw %}	Creates a new step called Log in to GitHub Docker Registry, which logs in to the registry using the account and password that will publish the packages. Once published, the packages are owned by the account defined here.
  {% raw %} - name: Build container image {% endraw %}	Creates a new step called Build container image. This step runs as part of the build-and-push-image job.
  {% raw %} uses: docker/build-push-action@v2 {% endraw %}	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 {% data variables.product.prodname_registry %}.
  {% raw %} with: {% endraw %}	Sends the required parameters to the build-push-action action. This are defined in the subsequent lines.
  {% raw %} push: true {% endraw %}	Push this image to the registry if it is built successfully.
  tags: | {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.sha }}{% endraw %} {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.ref }}{% endraw %}	Tags the published package with the git ref (for example, the name of the branch used to create the package) as well as the commit SHA.

  • 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 {% data variables.product.prodname_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 {% data variables.product.prodname_registry %}. Then, the workflow can run CI tests that require the dependencies.

  Installing packages hosted by {% data variables.product.prodname_registry %} through {% data variables.product.prodname_actions %} requires minimal configuration or additional authentication when you use the GITHUB_TOKEN.{% if currentVersion == "free-pro-team@latest" %} Data transfer is also free when an action installs a package. For more information, see "About billing for {% data variables.product.prodname_registry %}."{% endif %}

  {% data reusables.package_registry.actions-configuration %}

  {% if currentVersion == "free-pro-team@latest" %}

  Upgrading a workflow that accesses ghcr.io

  {% data reusables.package_registry.github-token-security-over-pat %}

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

  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."

  {% endnote %} 3. 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 login to ghcr.io, replace your PAT with {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}.

  For example, this workflow publishes a Docker container using {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} 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{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %}
      permissions:
        packages: write
        contents: read{% endif %}
  
      {% raw %}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
          # 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{% endraw %}
  

  {% endif %}