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 "Learn GitHub Actions."

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

To authenticate to package registries on GitHub Enterprise Server, we recommend using the GITHUB_TOKEN that GitHub Enterprise Server automatically creates for your repository when you enable GitHub Actions. 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 "Automatic token authentication."

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

About permissions and package access

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 "Automatic token authentication."

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

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

The following example demonstrates how you can use GitHub Actions to build and test 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:

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.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

name: Create and publish a Docker image

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@v2
        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@v2
        with:
          node-version: ${{ matrix.node-version }}
      - uses: actions/download-artifact@v2
        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@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - 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 }}

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

Code	Explanation
`on: push: branches: ['release']`	Configures the `Create and publish a Docker image` 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@v2 - name: npm install and build webpack run: \| npm install npm run build - uses: actions/upload-artifact@v2 with: name: webpack artifacts path: public/`	This job installs npm and uses it to build the app.
`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@v2 with: node-version: ${{ matrix.node-version }} - uses: actions/download-artifact@v2 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. The `needs: run-npm-build` command 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. The `needs: run-npm-test` command 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.
`- 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 }}`	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 scoped to the account defined here.
`- name: Build and push Docker image`	Creates a new step called `Build and push Docker image`. This step runs as part of the `build-and-push-image` job.
`uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4`	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.
`with:`	Sends the required parameters to the `build-push-action` action. These are defined in the subsequent lines.
`push: true`	Pushes this image to the registry if it is built successfully.
`tags: \| docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}`	Tags the image with the SHA of the commit that triggered the workflow.

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