Docker with GitHub Actions: Build, Cache, and Deploy Without the Pain

You've been burned by 'it works on my machine' one too many times. Docker fixes that, but only if your CI/CD pipeline actually builds the same image you tested locally. GitHub Actions is the most popular CI/CD platform on the planet, and yet I still see teams pushing 2GB images because they don't understand layer caching. Here's the blunt truth: your pipeline is probably slower and more fragile than it should be.

The core problem is that most tutorials show you how to run docker build in a workflow and call it a day. They ignore the real-world constraints: limited runner disk space, network egress costs, and the fact that rebuilding an image from scratch every time is a waste of time and money. You need a pipeline that's fast, reliable, and doesn't cost a fortune in GitHub Actions minutes.

By the end of this article, you'll be able to set up a production-grade Docker CI/CD pipeline that caches intelligently, builds multi-architecture images, and deploys securely — all while avoiding the gotchas that have taken down production services at 3 AM.

Why Your Docker Builds Are Slow (And How to Fix It)

Every time you run docker build, Docker executes each instruction in your Dockerfile, creating a new layer. If nothing changed, Docker uses the cached layer — but only if the context and previous layers are identical. The problem: GitHub Actions runners are ephemeral. They start fresh each time, so your local cache is gone. Without caching, you rebuild every layer from scratch. That's slow and expensive.

The fix is to use Docker's --cache-from flag to pull cached layers from a registry. GitHub Actions has a built-in cache action, but for Docker, the best approach is to use the docker/build-push-action with cache-from and cache-to pointing to the same registry where you push the final image. This way, layers are stored alongside your image, and subsequent builds reuse them.

# io.thecodeforge — DevOps tutorial
# Production Docker build with layer caching

name: Build and Push Docker Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: yourusername/yourapp:latest
          # Cache from previous build in registry
          cache-from: type=registry,ref=yourusername/yourapp:cache
          # Cache to registry for next build
          cache-to: type=registry,ref=yourusername/yourapp:cache,mode=max

Multi-Architecture Builds: Arm64 Without the Headache

Apple Silicon is everywhere, and AWS Graviton instances are cheap. If you're still building only for amd64, you're leaving performance and cost on the table. But building for multiple architectures manually is a pain. Docker Buildx makes it trivial with the --platform flag.

In GitHub Actions, you can build for linux/amd64 and linux/arm64 in one step using QEMU emulation. The trick is to set up QEMU before the build and use a matrix strategy if you need separate builds per architecture. For most cases, a single build with multiple platforms works fine, but be aware: QEMU emulation is slow. For large images, consider native arm64 runners (GitHub now offers them).

# io.thecodeforge — DevOps tutorial
# Multi-architecture Docker build

name: Multi-Arch Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push multi-arch
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: yourusername/yourapp:latest
          cache-from: type=registry,ref=yourusername/yourapp:cache
          cache-to: type=registry,ref=yourusername/yourapp:cache,mode=max

Secrets Management: Don't Hardcode Credentials

I've seen Dockerfiles with ENV API_KEY=supersecret committed to public repos. That's a fireable offense. GitHub Actions provides secrets, but you need to pass them to Docker correctly. The naive approach is to use --build-arg, but that leaks secrets into the image history. Instead, use Docker's --secret flag (BuildKit) to mount secrets at build time without persisting them.

For runtime secrets, pass them as environment variables in the container using GitHub secrets. Never bake secrets into the image.

# io.thecodeforge — DevOps tutorial
# Passing secrets to Docker build securely

name: Secure Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build with secret
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: yourusername/yourapp:latest
          secrets: |
            "npmrc=${{ secrets.NPMRC }}"
          cache-from: type=registry,ref=yourusername/yourapp:cache
          cache-to: type=registry,ref=yourusername/yourapp:cache,mode=max

Testing Your Docker Image in CI Before Push

Building an image is useless if it doesn't work. You should run integration tests against the freshly built image before pushing it to the registry. The pattern: build the image, run it as a service container, execute tests against it, then push only if tests pass.

GitHub Actions supports service containers natively. You can spin up your Docker image as a service, run tests in a separate job step, and conditionally push based on the test result. This prevents broken images from reaching production.

# io.thecodeforge — DevOps tutorial
# Build, test, then push Docker image

name: Test and Push

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      app:
        image: yourusername/yourapp:test-${{ github.sha }}
        ports:
          - 3000:3000
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3

      - name: Build test image
        uses: docker/build-push-action@v5
        with:
          context: .
          load: true
          tags: yourusername/yourapp:test-${{ github.sha }}
          cache-from: type=registry,ref=yourusername/yourapp:cache

      - name: Run integration tests
        run: |
          curl -f http://localhost:3000/health || exit 1
          # More tests...

  push:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push production image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: yourusername/yourapp:latest
          cache-from: type=registry,ref=yourusername/yourapp:cache
          cache-to: type=registry,ref=yourusername/yourapp:cache,mode=max

When Not to Use Docker with GitHub Actions

Docker in CI is not always the answer. If your application is a simple static site, deploying directly to a CDN (like Netlify or Vercel) is faster and cheaper. If you're running a monolith that rarely changes, a traditional VM deployment might be simpler. Docker adds complexity: you need to manage a registry, handle image cleanup, and deal with build failures due to cache invalidation.

Also, if your team doesn't have Docker expertise, the learning curve can slow down development. For small projects or prototypes, consider using GitHub Actions' built-in deploy actions (like azure/webapps-deploy or google-github-actions/deploy-cloudrun) that handle containerization for you.

My rule of thumb: use Docker in CI when you have multiple services, need consistent environments across dev/staging/prod, or are deploying to Kubernetes. Otherwise, keep it simple.