Using GitHub Packages 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 package registries on GitHub

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 instead of a personal access token for authentication. It has read and write permissions for packages in the repository where the workflow runs. 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.

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

  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
      steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Build container image
        uses: docker/build-push-action@v1
        with: 
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
          registry: docker.pkg.github.com
          repository: ${{ github.repository }}/octo-image 
          tag_with_sha: true
          tag_with_ref: true 

  The relevant settings are explained in the following table:

  on: push: branches: ['release']	Configures the Create and publish a package 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@main 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: [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	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.
  - name: Build container image	Creates a new step called Build container image. This step runs as part of the build-and-push-image job. The needs: run-npm-test command makes this job dependent on the run-npm-test job.
  uses: docker/build-push-action@v1	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. This are defined in the subsequent lines.
  username: ${{ github.actor }}	Defines the user account that will publish the packages. Once published, the packages are owned by the account defined here.
  password: ${{ secrets.GITHUB_TOKEN }}	Defines the password that is used to access GitHub Packages.
  registry: docker.pkg.github.com	Defines the registry that will host the resulting packages. This example uses GitHub Packages.
  repository: ${{ github.repository }}/octo-image	Defines which repository will host the resulting package, and sets the name of the published package. Replace octo-image with the name you want for your package.
  tag_with_sha: true	Tags the published package with the first seven characters of the commit's SHA. For example, sha-2f2d842.
  tag_with_ref: true	Tags the published package with the git ref. This can be the name of the branch used to create the package.

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

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