About this project

This is a GitHub Action intended to simplify the process for building automated Docker images with GitHub Actions.

Features:

• ✅ Stupid simple to use - just pass in the tags, registry, and credentials and you're good to go
• 🚀 Customize your docker image names/tags - easily pass in what you want it to be
• 🤓 Multi-arch support - build for multiple architectures
• 📦 Multi-registry support - build and push to up to 3 registries simultaneously (Docker Hub, GitHub Container Registry, and private registries)
• 🔀 Context aware - great if you have a Dockerfile in a different part of your repo
• ⚡ Build cache support - pass cache-from/cache-to straight through to reuse layers between runs

Usage

Single Registry Example

Here is a basic example workflow for publishing to a single registry:

name: Docker Publish (Production Images)
on:
  push:

jobs:
  docker-publish:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Build and push Docker image
        uses: serversideup/github-action-docker-build@v6
        with:
          tags: serversideup/financial-freedom:latest
          registry-username: ${{ secrets.DOCKER_HUB_USERNAME }}
          registry-password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
          platforms: "linux/amd64,linux/arm/v7,linux/arm64/v8"

Multiple Registry Example

You can now push to up to 3 different registries in a single build! Perfect for publishing to Docker Hub, GitHub Container Registry, and your own private registry simultaneously:

name: Docker Publish (Multiple Registries)
on:
  push:
    branches:
      - main

jobs:
  docker-publish:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Build and push to multiple registries
        uses: serversideup/github-action-docker-build@v6
        with:
          # Tag with multiple registry prefixes
          tags: |
            docker.io/myorg/myapp:latest
            ghcr.io/myorg/myapp:latest
            registry.example.com/myapp:latest
          
          # Registry 1: Docker Hub
          registry: "docker.io"
          registry-username: ${{ secrets.DOCKER_HUB_USERNAME }}
          registry-password: ${{ secrets.DOCKER_HUB_TOKEN }}
          
          # Registry 2: GitHub Container Registry
          registry-2: "ghcr.io"
          registry-2-username: ${{ github.actor }}
          registry-2-password: ${{ secrets.GITHUB_TOKEN }}
          
          # Registry 3: Custom Private Registry
          registry-3: "registry.example.com"
          registry-3-username: ${{ secrets.CUSTOM_REGISTRY_USER }}
          registry-3-password: ${{ secrets.CUSTOM_REGISTRY_TOKEN }}
          
          platforms: "linux/amd64,linux/arm64"

💡 Pro tip: You only need to specify the registries you want to use. Registry 2 and 3 are optional and will be skipped if credentials aren't provided.

Build Cache Example

GitHub-hosted runners give you a fresh VM on every job, so builds start cold unless you bring a cache with you. Pass cache-from and cache-to to reuse layers between runs.

The quickest option is GitHub's own Actions cache:

      - name: Build and push Docker image
        uses: serversideup/github-action-docker-build@v6
        with:
          tags: serversideup/financial-freedom:latest
          registry-username: ${{ secrets.DOCKER_HUB_USERNAME }}
          registry-password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

If you'd rather keep the cache next to your image, store it in your registry instead. This avoids the 10GB Actions cache limit and stays shared across branches:

name: Docker Publish (Registry Cache)
on:
  push:
    branches:
      - main

permissions:
  contents: read
  packages: write

jobs:
  docker-publish:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and push Docker image
        uses: serversideup/github-action-docker-build@v6
        with:
          tags: ghcr.io/myorg/myapp:latest
          registry: "ghcr.io"
          registry-username: ${{ github.actor }}
          registry-password: ${{ secrets.GITHUB_TOKEN }}
          cache-from: type=registry,ref=ghcr.io/myorg/myapp/buildcache:latest
          cache-to: type=registry,ref=ghcr.io/myorg/myapp/buildcache:latest,mode=max

💡 Pro tip: mode=max caches every layer, including intermediate build stages. Without it you only cache the layers that ship in your final image, which usually misses the expensive ones like composer install, npm ci, and compile steps.

Configuration options

🔀 Input Name	📚 Description	🛑 Required	👉 Default
tags	Enter the tag(s) you would like to name your image with. (example: myorg/myapp:production) Use multi-line format for multiple tags.	⚠️ Yes
registry	Choose which container image repository to upload to. See all options.		docker.io
registry-username	Enter the username to authenticate with your first registry.	⚠️ Yes
registry-password	Enter the password or token to authenticate with your registry. (an access token is highly recommended)	⚠️ Yes
registry-token (deprecated)	Use registry-password instead
context	The build context directory (the directory containing your Dockerfile and build files).		.
dockerfile	Filename of the Dockerfile within the context that you set.		./Dockerfile
platforms	Comma separated list of platforms.		linux/amd64
target	The target build stage to build.
cache-from	List of external cache sources for the build (e.g., type=gha). Passed directly to docker/build-push-action.
cache-to	List of cache export destinations for the build (e.g., type=gha,mode=max). Passed directly to docker/build-push-action.

If you have more than one registry

🔀 Input Name	📚 Description	🛑 Required	👉 Default
registry-2	Choose which container image repository to upload to. See all options.
registry-2-username	Enter the username to authenticate with your second registry.	⚠️ Yes (if you use the 2nd registry)
registry-2-password	Enter the token or password to authenticate with your second registry. (an access token is highly recommended)	⚠️ Yes (if you use the 2nd registry)
registry-3	Choose which container image repository to upload to. See all options.
registry-3-username	Enter the username to authenticate with your third registry.	⚠️ Yes (if you use the 3rd registry)
registry-3-password	Enter the token or password to authenticate with your third registry. (an access token is highly recommended)	⚠️ Yes (if you use the 3rd registry)

Note

At least one registry's credentials must be provided (either registry 1, 2, or 3).

Important security notice

Always use encrypted secrets when passing sensitive information. Learn more here →

Security Disclosures

If you find a security vulnerability, please let us know as soon as possible.

View Our Responsible Disclosure Policy →

Our Sponsors

All of our software is free and open to the world. None of this can be brought to you without the financial backing of our sponsors.

Platinum Sponsors

Silver Sponsors

Infrastructure Sponsors

These companies give us free access to the tools and infrastructure we use to build, test, and ship our open source projects. Their support helps our entire community.

  

About Us

We're Dan and Jay - a two-person team with a passion for open source products. We created Server Side Up to help share what we learn.

Dan Pastori	Jay Rogers

Hire Us

Get two senior Laravel experts who deliver quality code with predictable monthly pricing. Dan and Jay have 30+ years of combined experience building scalable Laravel applications.

• 🎯 Complete Laravel expertise - Full-stack development, CI/CD, database optimization, mobile apps
• 💰 Predictable pricing - Fixed monthly subscription, no hourly billing surprises, 40%+ savings
• ⚡ Maximum productivity - 90%+ development time, no meetings, results in days not weeks
• 🛡️ Risk-free - 7-day money-back guarantee, cancel anytime

💬 Discuss Your Project →

Find us at:

• 📖 Blog - Get the latest guides and free courses on all things web/mobile development.
• 🙋 Community - Get friendly help from our community members.
• 🤵‍♂️ Get Professional Help - Get video + screen-sharing support from the core contributors.
• 💻 GitHub - Check out our other open source projects.
• 📫 Newsletter - Skip the algorithms and get quality content right to your inbox.
• 🐥 X (Twitter) - You can also follow Dan and Jay.
• ❤️ Sponsor Us - Please consider sponsoring us so we can create more helpful resources.

Our Products

If you appreciate this project, be sure to check out our other projects.

🛠️ Premium

• Self-Host Pro: Sell self-hosted software in minutes.
• Spin Pro: Production-ready Docker templates for shipping quickly.

🌍 Open Source

• serversideup/php: Supercharged PHP Docker images, based off the official PHP images.
• Spin: Docker Simplified. Deploy Anywhere. Zero Downtime. Any OS.
• Financial Freedom: Open source alternative to Mint, YNAB, and more.
• AmplitudeJS: Customize the design of any element of the HTML5 Audio Player.
• webext-bridge: Messaging in Web Extensions made easy. Batteries included.
• serversideup/ansible: Run Ansible anywhere with a lightweight and powerful Docker image.

📚 Books

• Building Browser Extensions: Build browser extensions for Firefox, Chrome, and more.
• Ultimate Guide To Building APIs & SPAs: Build web and mobile apps from the same codebase.