Optimizing Container Delivery via GitHub Actions Build and Push Workflows

The integration of containerization into Continuous Integration and Continuous Deployment (CI/CD) pipelines has transformed how software is delivered, with building and pushing Docker images serving as a foundational requirement for modern cloud-native applications. Within the GitHub Actions ecosystem, the process of transforming source code into a deployable artifact involves a sophisticated chain of events: source checkout, environment preparation, image construction, and final distribution to a container registry. This process is facilitated by a variety of specialized actions, ranging from the industry-standard docker/build-push-action to highly optimized alternatives like those provided by Depot or specialized community actions like flamestro/build-push-github-action.

The core objective of these workflows is to ensure that every commit or release tag results in a consistent, immutable image that can be deployed across various environments. This requires not only the ability to execute a docker build command but also the management of multi-architecture support, efficient layer caching to reduce build times, and secure authentication with registries such as the GitHub Container Registry (GHCR) or Docker Hub. By leveraging the Moby BuildKit builder toolkit, developers can implement advanced features like remote caching and multi-platform manifests, ensuring that images run natively on both x86_64 and ARM64 architectures without the overhead of emulation in production.

Architectural Overview of Docker Build and Push Actions

The ecosystem for building and pushing images on GitHub Actions is dominated by the implementation of Buildx, which is the Docker CLI plugin that extends the build capabilities of Docker. Most high-performance actions, including the docker/build-push-action, rely on the BuildKit backend. This allows for a more efficient build process where layers can be processed in parallel and cache can be exported to external backends.

The standard workflow typically involves several discrete steps before the actual build and push action is invoked. First, the actions/checkout@v4 action is used to pull the repository code into the runner. Second, if multi-platform builds are required, docker/setup-qemu-action@v3 is deployed to provide the necessary emulation for different CPU architectures. Third, docker/setup-buildx-action@v3 is utilized to create and boot a builder, typically using the docker-container driver. This driver is essential because it provides the isolated environment necessary for BuildKit to operate with full feature support, including secrets and remote cache management.

Finally, authentication is handled via docker/login-action@v3. This step ensures that the runner has the necessary credentials to push the resulting image to a private or public registry. Whether using the GITHUB_TOKEN for GHCR or specific secrets for Docker Hub, this authentication layer is the gatekeeper for the final push operation.

Comprehensive Analysis of the docker/build-push-action

The docker/build-push-action is the primary tool for building and pushing Docker images with full support for the Moby BuildKit builder toolkit. Its design allows for a high degree of customization, making it suitable for everything from simple hobby projects to complex enterprise microservices architectures.

Core Functionalities and Technical Capabilities

The action provides a comprehensive set of features that extend beyond simple image creation. By utilizing BuildKit, it supports:

• Multi-platform builds: The ability to create images for multiple architectures (e.g., linux/amd64, linux/arm64) in a single run.
• Secret management: Securely passing build-time secrets without baking them into the final image layers.
• Remote cache: The ability to push and pull cache layers from a registry, significantly speeding up subsequent builds.
• Flexible namespacing: Different options for builder deployment and naming to avoid conflicts in shared environments.

Implementation and Workflow Integration

To implement this action effectively, it is often paired with the docker/metadata-action@v5. This companion action automates the generation of tags and labels based on Git metadata, removing the need for manual tagging. For example, tags can be automatically generated based on the branch name, the Pull Request number, semantic versioning from git tags, or the short SHA of the commit.

A typical implementation for a production-ready pipeline looks as follows:

```yaml
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha,prefix=

• name: Build and push
  uses: docker/build-push-action@v5
  with:
  context: .
  push: ${{ github.eventname != 'pullrequest' }}
  tags: ${{ steps.meta.outputs.tags }}
  labels: ${{ steps.meta.outputs.labels }}
  cache-from: type=gha
  cache-to: type=gha,mode=max
  ```

In this configuration, the push parameter is conditionally set so that images are only pushed on the main branch or tags, while PRs only trigger a build to verify that the Dockerfile is valid.

Specialized Alternatives and Performance Optimizations

While the standard Docker action is versatile, specific use cases may require different tools, particularly when build speed becomes a bottleneck or when simplifying the GHCR integration.

Depot: High-Performance Build Compute

The depot/build-push-action is designed for teams that require extreme build speed. It implements the same inputs and outputs as the docker/build-push-action, ensuring a seamless transition for users, but it swaps the execution backend for the Depot CLI.

The primary advantage of Depot is the use of optimized build compute and a Docker cache that is persisted on SSDs. This architectural choice allows Depot to achieve build speeds that are 5-20x faster than standard GitHub Actions runners. To use Depot, the depot/setup-action@v1 must be included in the workflow to install the CLI. Authentication is handled via a Depot API token, which can be inferred from the environment or supplied explicitly. Depot also provides native support for multi-architecture builds, eliminating some of the overhead associated with traditional emulation.

flamestro/build-push-github-action

For users who need a streamlined path to the GitHub Container Registry (GHCR), the flamestro/[email protected] offers a specialized experience. This action is specifically tailored to publish images to ghcr.io and requires a Dockerfile to be present in the repository.

The configuration for this action is more concise:

yaml - name: publish docker image uses: flamestro/[email protected] with: username: ${{ github.repository_owner }} token: ${{ secrets.GITHUB_TOKEN }} platforms: linux/amd64,linux/arm64 cache: true cache_scope: my-image-${{ matrix.arch }}

A critical security requirement for this action is that the GITHUB_TOKEN must be granted write access. This is configured in the repository settings under Actions -> General -> Workflow permissions, where "Read and write permissions" must be selected.

Detailed Caching Strategies for Build Acceleration

Caching is the most critical factor in reducing the "time to ship" in a CI/CD pipeline. Without caching, every build starts from the base image and re-runs every layer, leading to wasted compute time and slower feedback loops.

GitHub Actions (GHA) Cache

The recommended strategy for most users is the gha cache type. This stores the build cache directly within the GitHub Actions cache backend rather than in the registry. It is implemented using the following parameters:

• cache-from: type=gha
• cache-to: type=gha,mode=max

The mode=max setting ensures that all layers are cached, even those that are not used in the final image, which is particularly useful for multi-stage builds where earlier stages may be reused across different image variations.

Registry Cache

Alternatively, the registry cache stores the build cache as a separate image in the container registry. This is useful when builds are distributed across different runners or platforms where the GHA cache might not be available.

Implementation example:

yaml - name: Build with registry cache uses: docker/build-push-action@v5 with: context: . push: true tags: ghcr.io/${{ github.repository }}:latest cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:cache cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:cache

Comparison of Caching Mechanisms

Multi-Platform Build Execution and QEMU

Modern hardware diversity requires images that can run on both traditional servers (x86_64) and newer ARM-based instances (like AWS Graviton or Apple Silicon). GitHub Actions handles this through a combination of QEMU and Buildx.

The Role of QEMU

Because GitHub's standard runners are primarily x86_64, building an ARM64 image requires emulation. The docker/setup-qemu-action@v3 installs the necessary binaries to emulate different CPU architectures. Without this step, the build-push-action would fail when attempting to execute instructions for a non-native platform.

Multi-Platform Workflow Implementation

A complete multi-platform build workflow integrates these components as follows:

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

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

• name: Build and push multi-platform
  uses: docker/build-push-action@v5
  with:
  context: .
  platforms: linux/amd64,linux/arm64
  push: true
  tags: ghcr.io/${{ github.repository }}:latest
  ```

This process creates a "manifest list," a special type of image that points to the specific image for each architecture. When a user runs docker pull, Docker automatically selects the version that matches the user's host architecture.

Registry Integration and Authentication Patterns

The final stage of the build process is the push to a registry. Depending on the target (Docker Hub vs. GHCR), the authentication patterns differ.

GitHub Container Registry (GHCR)

GHCR is the preferred choice for GitHub users due to its deep integration. Authentication is typically handled using the GITHUB_TOKEN, which is automatically provided by GitHub to every workflow run.

yaml - name: Log in to GHCR uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }}

Using github.actor as the username ensures that the image is associated with the user who triggered the workflow.

Docker Hub

For distribution to the wider public via Docker Hub, separate secrets must be managed. It is highly recommended to use an Access Token rather than a password for security reasons.

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

Comparative Analysis of Build Action Options

Depending on the project's scale and performance needs, the choice of action will vary.

Conclusion

The orchestration of Docker builds within GitHub Actions is a sophisticated process that balances speed, compatibility, and security. By moving from basic docker build commands to professional actions like docker/build-push-action, developers gain access to critical features such as multi-platform support and advanced caching. The integration of setup-qemu-action and setup-buildx-action transforms the GitHub runner into a powerful build station capable of producing images for any target architecture.

Furthermore, the emergence of specialized providers like Depot demonstrates the ongoing evolution of build compute, where SSD-backed caching and optimized environments can drastically reduce development cycles. Whether utilizing the standard GHA cache for cost-efficiency or the registry cache for maximum portability, the strategic management of image layers is essential for maintaining a performant pipeline. Ultimately, the combination of metadata-driven tagging and secure registry authentication ensures that the journey from code commit to a deployed container is automated, repeatable, and secure.

Sources

1. build-push-github-action
2. depot/build-push-action
3. docker/build-push-action
4. build-and-push-docker-images
5. OneUptime Blog - GitHub Actions Docker Build Push