Text of docs.docker.com › build › ci › github-actions as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

Docker Build GitHub Actions | Docker Docs

Start a new chat Answers are generated based on the documentation. Manuals Get started Guides Reference Docker Build GitHub Actions Table of contents GitHub Actions automates your build, test, and deployment pipeline. Use Docker GitHub Builder to build and publish images with Docker-maintained reusable workflows. GitHub Builder manages Buildx setup, platform distribution, metadata, and signing. Start with GitHub Builder for supported build tasks, and compose individual actions when you need custom job steps or controls outside the reusable workflow interface.

Get started Build an image from your GitHub repository and push it to Docker Hub with the following workflow. Prerequisites A GitHub repository with your application and a Dockerfile at its root. A Docker Hub account and a personal access token with permission to push images. Configure your GitHub repository Add your Docker Hub credentials to your GitHub repository: Open your repository's Settings . Under Security , go to Secrets and variables > Actions .

Under Secrets , create a repository secret named DOCKERHUB_TOKEN containing your Docker access token. Under Variables , create a repository variable named DOCKERHUB_USERNAME containing your Docker Hub username. Set up your GitHub Actions workflow Create .github/workflows/docker-ci.yml in your repository with the following contents. Replace my-image with the name of your Docker Hub repository, and change main if your default branch has a different name. name : ci on : push : branches : - main pull_request : jobs : build : uses : docker/github-builder/.github/workflows/build.yml@v1 permissions : contents : read id-token : write with : output : image push : ${{ github.event_name != 'pull_request' }} set-meta-labels : true set-meta-annotations : true meta-images : ${{ vars.DOCKERHUB_USERNAME }}/my-image secrets : registry-auths : | - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} Call the reusable workflow with uses at the job level, rather than inside steps .

Grant contents: read to fetch the repository and id-token: write for signing with GitHub's OpenID Connect token. With the default sign: auto , GitHub Builder signs attestation manifests when pushing an image. See the Build workflow for inputs and outputs. Commit the workflow file and push it to your default branch to run it. The workflow also runs on pull requests. With push: false , the default registry-login: auto skips registry login and sign: auto skips signing.

Pull requests from forks can build without Docker Hub secrets or a writable OpenID Connect token. Builds that need private dependencies still need access to those dependencies. GitHub Builder builds from the repository at the triggering Git reference. Files changed in a caller job aren't included in the build. GitHub Builder uses the metadata action to generate tags from the GitHub event. For example, a push to main publishes DOCKERHUB_USERNAME/my-image:main .

The set-meta-labels and set-meta-annotations switches also apply generated labels and annotations; both are disabled by default. See Manage tags and labels and Annotations to customize this metadata. This workflow builds images but doesn't run application tests. To add tests, see Test before push . For additional build options, see Multi-platform images and SBOM and provenance attestations . Use the Build workflow for Dockerfile inputs, or the Bake workflow for a build defined in Bake.

Both support image and local file output. For details on platform distribution and outputs, see GitHub Builder architecture . Build with individual actions Use individual actions to load images into a job's Docker image store, run steps before or after a build on the same runner, or configure the builder directly. GitHub Builder's image output publishes to a registry; its local output exports files. Neither loads an image into the caller's Docker image store or exports a Docker image archive.

The following alternative uses the same credentials, triggers, and metadata as the GitHub Builder example: name : Build and push Docker image on : push : branches : - main pull_request : permissions : contents : read jobs : build : runs-on : ubuntu-latest steps : - name : Extract Docker image metadata id : meta uses : docker/metadata-action@v6 with : images : ${{ vars.DOCKERHUB_USERNAME }}/my-image - name : Sign in to Docker Hub if : github.event_name != 'pull_request' uses : docker/login-action@v4 with : username : ${{ vars.DOCKERHUB_USERNAME }} password : ${{ secrets.DOCKERHUB_TOKEN }} - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Build and push Docker image uses : docker/build-push-action@v7 with : push : ${{ github.event_name != 'pull_request' }} tags : ${{ steps.meta.outputs.tags }} labels : ${{ steps.meta.outputs.labels }} annotations : ${{ steps.meta.outputs.annotations }} The build action uses Git context by default: BuildKit fetches the repository at the triggering Git reference.

No checkout step is needed, and changes made by earlier steps aren't included. Use a checkout and a path context when the build needs files changed by earlier steps. Available actions The following GitHub Actions are available: Build and push Docker images : build and push Docker images with BuildKit. Docker Buildx Bake : enables using high-level builds with Bake . Docker Login : sign in to a Docker registry. Docker Setup Buildx : creates and boots a BuildKit builder.

Docker Metadata action : extracts metadata from Git reference and GitHub events to generate tags, labels, and annotations. Docker Setup Compose : installs and sets up Compose . Docker Setup Docker : installs Docker Engine. Docker Setup QEMU : installs QEMU static binaries for multi-platform builds. Docker Scout : analyze Docker images for security vulnerabilities.