Introduction

This guide shows you how to create a workflow that performs a Docker build, and then publishes Docker images to Docker Hub or GitHub Packages. With a single workflow, you can publish images to a single registry or to multiple registries.

Prerequisites

We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, seeWriting workflows.

You might also find it helpful to have a basic understanding of the following:

• Using secrets in GitHub Actions
• Use GITHUB_TOKEN for authentication in workflows
• Working with the Container registry

About image configuration

This guide assumes that you have a complete definition for a Docker image stored in a GitHub repository. For example, your repository must contain aDockerfile, and any other files needed to perform a Docker build to create an image.

You can use pre-defined annotation keys to add metadata including a description, a license, and a source repository to your container image. For more information, seeWorking with the Container registry.

In this guide, we will use the Dockerbuild-push-action action to build the Docker image and push it to one or more Docker registries. For more information, seebuild-push-action.

Publishing images to Docker Hub

Each time you create a new release on GitHub, you can trigger a workflow to publish your image. The workflow in the example below runs when therelease event triggers with thepublished activity type.

In the example workflow below, we use the Dockerlogin-action andbuild-push-action actions to build the Docker image and, if the build succeeds, push the built image to Docker Hub.

To push to Docker Hub, you will need to have a Docker Hub account, and have a Docker Hub repository created. For more information, seePushing a Docker container image to Docker Hub in the Docker documentation.

Thelogin-action options required for Docker Hub are:

• username andpassword: This is your Docker Hub username and password. We recommend storing your Docker Hub username and password as secrets so they aren't exposed in your workflow file. For more information, seeUsing secrets in GitHub Actions.

Themetadata-action option required for Docker Hub is:

• images: The namespace and name for the Docker image you are building/pushing to Docker Hub.

Thebuild-push-action options required for Docker Hub are:

• tags: The tag of your new image in the formatDOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION. You can set a single tag as shown below, or specify multiple tags in a list.
• push: If set totrue, the image will be pushed to the registry if it is built successfully.

# 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: Publish Docker imageon:  release:    types: [published]jobs:  push_to_registry:    name: Push Docker image to Docker Hub    runs-on: ubuntu-latest    permissions:      packages: write      contents: read      attestations: write      id-token: write    steps:      - name: Check out the repo        uses: actions/checkout@v5      - name: Log in to Docker Hub        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a        with:          username: ${{ secrets.DOCKER_USERNAME }}          password: ${{ secrets.DOCKER_PASSWORD }}      - name: Extract metadata (tags, labels) for Docker        id: meta        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7        with:          images: my-docker-hub-namespace/my-docker-hub-repository      - name: Build and push Docker image        id: push        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671        with:          context: .          file: ./Dockerfile          push: true          tags: ${{ steps.meta.outputs.tags }}          labels: ${{ steps.meta.outputs.labels }}      - name: Generate artifact attestation        uses: actions/attest-build-provenance@v3        with:          subject-name: index.docker.io/my-docker-hub-namespace/my-docker-hub-repository          subject-digest: ${{ steps.push.outputs.digest }}          push-to-registry: true

# 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:PublishDockerimageon:release:types: [published]jobs:push_to_registry:name:PushDockerimagetoDockerHubruns-on:ubuntu-latestpermissions:packages:writecontents:readattestations:writeid-token:writesteps:-name:Checkouttherepouses:actions/checkout@v5-name:LogintoDockerHubuses:docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20awith:username:${{secrets.DOCKER_USERNAME}}password:${{secrets.DOCKER_PASSWORD}}-name:Extractmetadata(tags,labels)forDockerid:metauses:docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7with:images:my-docker-hub-namespace/my-docker-hub-repository-name:BuildandpushDockerimageid:pushuses:docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671with:context:.file:./Dockerfilepush:truetags:${{steps.meta.outputs.tags}}labels:${{steps.meta.outputs.labels}}-name:Generateartifactattestationuses:actions/attest-build-provenance@v3with:subject-name:index.docker.io/my-docker-hub-namespace/my-docker-hub-repositorysubject-digest:${{steps.push.outputs.digest}}push-to-registry:true

The above workflow checks out the GitHub repository, uses thelogin-action to log in to the registry, and then uses thebuild-push-action action to: build a Docker image based on your repository'sDockerfile; push the image to Docker Hub, and apply a tag to the image.

In the last step, it generates an artifact attestation for the image, which increases supply chain security. For more information, seeUsing artifact attestations to establish provenance for builds.

Publishing images to GitHub Packages

Each time you create a new release on GitHub, you can trigger a workflow to publish your image. The workflow in the example below runs when a change is pushed to therelease branch.

In the example workflow below, we use the Dockerlogin-action,metadata-action, andbuild-push-action actions to build the Docker image, and if the build succeeds, push the built image to GitHub Packages.

Thelogin-action options required for GitHub Packages are:

• registry: Must be set toghcr.io.
• username: You can use the${{ github.actor }} context to automatically use the username of the user that triggered the workflow run. For more information, seeContexts reference.
• password: You can use the automatically-generatedGITHUB_TOKEN secret for the password. For more information, seeUse GITHUB_TOKEN for authentication in workflows.

Themetadata-action option required for GitHub Packages is:

• images: The namespace and name for the Docker image you are building.

Thebuild-push-action options required for GitHub Packages are:

• context: Defines the build's context as the set of files located in the specified path.
• push: If set totrue, the image will be pushed to the registry if it is built successfully.
• tags andlabels: These are populated by output frommetadata-action.

#name: Create and publish a Docker image# Configures this workflow to run every time a change is pushed to the branch called `release`.on:  push:    branches: ['release']# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.env:  REGISTRY: ghcr.io  IMAGE_NAME: ${{ github.repository }}# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.jobs:  build-and-push-image:    runs-on: ubuntu-latest    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.    permissions:      contents: read      packages: write      attestations: write      id-token: write      #    steps:      - name: Checkout repository        uses: actions/checkout@v5      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.      - name: Log in to the Container registry        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1        with:          registry: ${{ env.REGISTRY }}          username: ${{ github.actor }}          password: ${{ secrets.GITHUB_TOKEN }}      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.      - name: Extract metadata (tags, labels) for Docker        id: meta        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7        with:          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}      # This step 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.      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.      - name: Build and push Docker image        id: push        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4        with:          context: .          push: true          tags: ${{ steps.meta.outputs.tags }}          labels: ${{ steps.meta.outputs.labels }}            # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).      - name: Generate artifact attestation        uses: actions/attest-build-provenance@v3        with:          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}          subject-digest: ${{ steps.push.outputs.digest }}          push-to-registry: true

name:CreateandpublishaDockerimage

on:push:branches: ['release']

env:REGISTRY:ghcr.ioIMAGE_NAME:${{github.repository}}

jobs:build-and-push-image:runs-on:ubuntu-latest

permissions:contents:readpackages:writeattestations:writeid-token:write

steps:-name:Checkoutrepositoryuses:actions/checkout@v5

-name:LogintotheContainerregistryuses:docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1with:registry:${{env.REGISTRY}}username:${{github.actor}}password:${{secrets.GITHUB_TOKEN}}

-name:Extractmetadata(tags,labels)forDockerid:metauses:docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7with:images:${{env.REGISTRY}}/${{env.IMAGE_NAME}}

-name:BuildandpushDockerimageid:pushuses:docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4with:context:.push:truetags:${{steps.meta.outputs.tags}}labels:${{steps.meta.outputs.labels}}

-name:Generateartifactattestationuses:actions/attest-build-provenance@v3with:subject-name:${{env.REGISTRY}}/${{env.IMAGE_NAME}}subject-digest:${{steps.push.outputs.digest}}push-to-registry:true

#name:CreateandpublishaDockerimage# Configures this workflow to run every time a change is pushed to the branch called `release`.on:push:branches: ['release']# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.env:REGISTRY:ghcr.ioIMAGE_NAME:${{github.repository}}# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.jobs:build-and-push-image:runs-on:ubuntu-latest# Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.permissions:contents:readpackages:writeattestations:writeid-token:write#steps:-name:Checkoutrepositoryuses:actions/checkout@v5# Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.-name:LogintotheContainerregistryuses:docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1with:registry:${{env.REGISTRY}}username:${{github.actor}}password:${{secrets.GITHUB_TOKEN}}# This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.-name:Extractmetadata(tags,labels)forDockerid:metauses:docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7with:images:${{env.REGISTRY}}/${{env.IMAGE_NAME}}# This step 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.# It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.# It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.-name:BuildandpushDockerimageid:pushuses:docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4with:context:.push:truetags:${{steps.meta.outputs.tags}}labels:${{steps.meta.outputs.labels}}# This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).-name:Generateartifactattestationuses:actions/attest-build-provenance@v3with:subject-name:${{env.REGISTRY}}/${{env.IMAGE_NAME}}subject-digest:${{steps.push.outputs.digest}}push-to-registry:true

The above workflow is triggered by a push to the "release" branch. It checks out the GitHub repository, and uses thelogin-action to log in to the Container registry. It then extracts labels and tags for the Docker image. Finally, it uses thebuild-push-action action to build the image and publish it on the Container registry.

Publishing images to Docker Hub and GitHub Packages

In a single workflow, you can publish your Docker image to multiple registries by using thelogin-action andbuild-push-action actions for each registry.

The following example workflow uses the steps from the previous sections (Publishing images to Docker Hub andPublishing images to GitHub Packages) to create a single workflow that pushes to both registries.

# 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: Publish Docker imageon:  release:    types: [published]jobs:  push_to_registries:    name: Push Docker image to multiple registries    runs-on: ubuntu-latest    permissions:      packages: write      contents: read      attestations: write      id-token: write    steps:      - name: Check out the repo        uses: actions/checkout@v5      - name: Log in to Docker Hub        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a        with:          username: ${{ secrets.DOCKER_USERNAME }}          password: ${{ secrets.DOCKER_PASSWORD }}      - name: Log in to the Container registry        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1        with:          registry: ghcr.io          username: ${{ github.actor }}          password: ${{ secrets.GITHUB_TOKEN }}      - name: Extract metadata (tags, labels) for Docker        id: meta        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7        with:          images: |            my-docker-hub-namespace/my-docker-hub-repository            ghcr.io/${{ github.repository }}      - name: Build and push Docker images        id: push        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671        with:          context: .          push: true          tags: ${{ steps.meta.outputs.tags }}          labels: ${{ steps.meta.outputs.labels }}      - name: Generate artifact attestation        uses: actions/attest-build-provenance@v3        with:          subject-name: ghcr.io/${{ github.repository }}          subject-digest: ${{ steps.push.outputs.digest }}          push-to-registry: true

# 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:PublishDockerimageon:release:types: [published]jobs:push_to_registries:name:PushDockerimagetomultipleregistriesruns-on:ubuntu-latestpermissions:packages:writecontents:readattestations:writeid-token:writesteps:-name:Checkouttherepouses:actions/checkout@v5-name:LogintoDockerHubuses:docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20awith:username:${{secrets.DOCKER_USERNAME}}password:${{secrets.DOCKER_PASSWORD}}-name:LogintotheContainerregistryuses:docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1with:registry:ghcr.iousername:${{github.actor}}password:${{secrets.GITHUB_TOKEN}}-name:Extractmetadata(tags,labels)forDockerid:metauses:docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7with:images:|            my-docker-hub-namespace/my-docker-hub-repository            ghcr.io/${{ github.repository }}-name:BuildandpushDockerimagesid:pushuses:docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671with:context:.push:truetags:${{steps.meta.outputs.tags}}labels:${{steps.meta.outputs.labels}}-name:Generateartifactattestationuses:actions/attest-build-provenance@v3with:subject-name:ghcr.io/${{github.repository}}subject-digest:${{steps.push.outputs.digest}}push-to-registry:true

The above workflow checks out the GitHub repository, uses thelogin-action twice to log in to both registries and generates tags and labels with themetadata-action action.Then thebuild-push-action action builds and pushes the Docker image to Docker Hub and the Container registry.

In the last step, it generates an artifact attestation for the image, which increases supply chain security. For more information, seeUsing artifact attestations to establish provenance for builds.