Running continuous integration and continuous deployment (CI/CD) jobs within containers represents a fundamental shift in how developers manage environment consistency, dependency management, and build reproducibility. In the GitHub Actions ecosystem, the ability to define a job’s execution environment via a container image eliminates the traditional friction of provisioning runtimes, installing language-specific packages, and configuring system libraries on ephemeral virtual machines. This approach ensures that the environment executing the code is identical to the environment used for development or production, thereby reducing the "it works on my machine" paradox.
While public container images offer immediate utility, enterprise and private workflows often require pulling from secure, private registries. Furthermore, the overhead of network transfer—pulling large image layers from remote repositories on each build—can significantly degrade pipeline performance. Advanced optimizations, such as those provided by specialized infrastructure providers like Depot, introduce ephemeral registries and accelerated build engines that reside on the same network as the runners. This architectural alignment reduces network latency, accelerates build times by up to 40x through layer caching, and cuts costs by leveraging optimized compute resources. Understanding the interplay between the runs-on host specification and the container execution environment is critical for designing efficient, secure, and high-performance CI/CD pipelines.
The Dual-Layer Execution Model: Host versus Container
A common point of confusion for developers new to containerized CI/CD is the requirement to specify both a runner host (runs-on) and a container image (container). These two directives serve distinct, non-interchangeable functions within the GitHub Actions architecture. The runs-on key dictates the underlying virtual machine (VM) or hardware environment that GitHub Actions provisions to execute the job. This host environment determines the operating system kernel, the container runtime (typically Docker), and the network interfaces available to the job.
The container key, conversely, defines the isolated user-space environment in which the actual job steps execute. When a job specifies runs-on: ubuntu-latest and container: centos-latest, the system provisions an Ubuntu-based virtual machine. Within that Ubuntu VM, the Docker daemon pulls the CentOS container image and executes the job steps inside that container. The host OS is essential because the container runtime itself is an OS-level feature; the host must support the container format (e.g., Linux containers) and provide the necessary kernel APIs. Skipping the runs-on specification is impossible because the platform must know what type of infrastructure to allocate before it can even download the container image.
This separation allows for flexibility in environment definition while maintaining strict infrastructure constraints. For instance, a developer might need to run a Linux container that requires specific ARM-based optimizations. They would specify runs-on with an ARM-compatible runner and container with an ARM-compatible image. The host provides the execution platform; the container provides the execution context.
yaml
name: Run job in a container
on:
push:
branches: main
jobs:
job-in-container:
runs-on: ubuntu-latest
container:
image: node:18
steps:
- name: echo node version
run: node --version
In this example, the job runs on an Ubuntu host, but the node --version command executes inside the node:18 container. This ensures that the Node.js version is exactly as defined in the Docker image, independent of the tools installed on the Ubuntu runner.
Environment Consistency and Dependency Management
One of the primary advantages of running jobs in containers is the elimination of setup steps. In a traditional runner-based workflow, jobs often begin with a series of actions to install languages, compilers, and dependencies. For example, a Python project might require actions/setup-python to install the runtime, followed by pip install commands to fetch libraries. These steps are not only time-consuming but also prone to version drift. If a library is updated in the background, a build that worked yesterday might fail today due to a breaking change in a dependency that was not pinned in the container image.
By baking the environment into the container image, developers achieve reproducible builds. The image serves as a snapshot of the entire environment: OS libraries, language runtimes, compilers, and application dependencies. This is particularly valuable for non-open-source projects that rely on private registries. While public images like node:18 are convenient, most enterprise codebases require proprietary tools or libraries that must be sourced from secure, authenticated registries such as Amazon ECR, Google Container Registry, or GitHub Container Registry (GHCR).
When using private registries, the GitHub Actions workflow must authenticate with the registry to pull the image. This is achieved by providing credentials in the container block. GitHub Actions supports passing environment variables, volumes, and credentials to the container, enabling complex setups such as mounting host directories for persistent data or setting environment variables that influence the container’s runtime behavior.
yaml
jobs:
container-test-job:
runs-on: ubuntu-latest
container:
image: node:18
env:
NODE_ENV: development
steps:
- name: Check for dockerenv file
run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)
If the workflow includes both script steps and container actions, GitHub Actions orchestrates the execution by running the container actions as sibling containers on the same network. These sibling containers share the same volume mounts, facilitating communication between the primary job container and auxiliary services (e.g., databases or message queues) that are also defined as containers.
Private Registry Authentication and Volume Mounting
For organizations using private container images, secure authentication is a prerequisite. GitHub Actions provides a mechanism to pass credentials to the container without exposing them in plain text. The credentials block within the container definition allows for the specification of a username and password, often derived from GitHub secrets or context variables.
In the case of GitHub Container Registry (GHCR), the github.actor context can be used as the username, and the GITHUB_TOKEN secret can be used as the password. This token is automatically generated for each workflow run and has the necessary permissions to pull images from the same organization. Additionally, volumes can be mounted from the host runner into the container. This is useful for accessing files generated by previous steps or for persistent storage that survives container restarts (though typically, ephemeral runners mean this is limited to the job duration).
yaml
name: Run job in a private container image
jobs:
job-in-container:
runs-on: ubuntu-latest
container:
image: ghcr.io/myorg/myimage
credentials:
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
volumes:
- /path/to/host/dir:/path/to/container/dir
env:
MY_ENV_VAR: my-value
This configuration ensures that the job runs inside ghcr.io/myorg/myimage, authenticated via the GitHub token, with a host directory mounted into the container and a specific environment variable set. This level of control is essential for complex builds that require access to internal artifacts or sensitive configuration data.
Accelerated Builds with Depot and Ephemeral Registries
While GitHub’s native runners provide a robust foundation, the bottleneck in container-based CI/CD often lies in the network transfer of container images. Every time a job runs, the runner must pull the image layers from a remote registry. For large images or slow network connections, this can add minutes to the build time. Furthermore, if the container image is built within the same workflow (e.g., a Dockerfile for the application itself), the build step must complete before the test step can begin, and the image must be pushed to a registry before it can be pulled by the next job.
Depot addresses these inefficiencies by integrating accelerated Docker builds, ephemeral registries, and managed runners into a cohesive ecosystem. The core innovation is the ephemeral registry: a temporary storage location for container images that exists only for the duration of the workflow. When a job builds an image using Depot’s build action, the image is saved in this ephemeral registry. Subsequent jobs in the same workflow can pull the image from this local registry without any network transfer to an external cloud service.
This approach reduces network transfer time and cost significantly. Since the Depot-managed builders and runners reside on the same network, the image data never leaves the local data center. This eliminates the latency associated with pulling from public or remote private registries. Additionally, Depot’s build engine accelerates Docker builds by up to 40x through persistent layer caching across builds. This means that if only a small part of the codebase changes, Depot reuses the cached layers from previous builds, drastically reducing the build time.
The integration also supports native CPU builds for both Intel and ARM architectures, ensuring that the image is built on the same architecture it will run on, avoiding emulation overhead.
yaml
name: Build container job image and run job with image
jobs:
build-job-container:
runs-on: ubuntu-latest
outputs:
buildId: ${{ steps.build.outputs.build-id}}
token: ${{ steps.pull-token.outputs.token }}
steps:
- name: Checkout code
uses: actions/checkout@v2
- uses: depot/setup-action@v1
- name: build and save the image
uses: depot/build-push-action@v1
id: build
with:
save: true
- name: export pull token
id: pull-token
run: echo "token=$(depot pull-token)" >> "$GITHUB_OUTPUT"
job-in-container:
needs: build-job-container
runs-on: ubuntu-latest
container:
image: registry.depot.dev/<your-project-id>:${{ needs.build-job-container.outputs.buildId }}
credentials:
username: x-token
password: ${{ needs.build-job-container.outputs.token }}
steps:
- name: run in container
run: echo "running in container"
In this workflow, the first job builds the image and saves it to the ephemeral registry. It then generates a pull token for that specific image. The second job, which depends on the first (needs: build-job-container), uses the build ID from the first job to construct the image name. It authenticates using the token generated in the first job and pulls the image directly from the ephemeral registry. This entire process occurs within the same network, bypassing external registry latency.
Optimizing Performance with Depot-Managed Runners
To further maximize performance, developers can route their jobs to Depot-managed GitHub Actions runners. These runners are optimized for CI/CD workloads and offer several advantages over standard GitHub-hosted runners. They provide 30% faster compute performance, 10x faster caching capabilities, and 1 GB/s network throughput. Additionally, they are available at half the cost of GitHub-hosted runners, making them an economically attractive option for high-frequency builds.
To use Depot-managed runners, the GitHub organization must be connected to Depot. This is done via the GitHub Actions tab in the Depot organization settings. Once connected, developers can replace the standard ubuntu-latest runner label with Depot-specific labels, such as depot-ubuntu-latest. This routes the job to a Depot-managed runner, which is already on the same network as the Depot build engine and ephemeral registry.
yaml
name: Build container job image and run job with image
jobs:
build-job-container:
runs-on: depot-ubuntu-latest
outputs:
buildId: ${{ steps.build.outputs.build-id}}
token: ${{ steps.pull-token.outputs.token }}
steps:
- name: Checkout code
uses: actions/checkout@v2
- uses: depot/setup-action@v1
- name: build and save the image
uses: depot/build-push-action@v1
id: build
with:
save: true
- name: export pull token
id: pull-token
run: echo "token=$(depot pull-token)" >> "$GITHUB_OUTPUT"
job-in-container:
needs: build-job-container
runs-on: depot-ubuntu-latest
container:
image: registry.depot.dev/<your-project-id>:${{ needs.build-job-container.outputs.buildId }}
credentials:
username: x-token
password: ${{ needs.build-job-container.outputs.token }}
steps:
- name: run in container
run: echo "running in container"
By using depot-ubuntu-latest for both the build and the job execution, the entire workflow is confined to Depot’s optimized infrastructure. The build step leverages accelerated caching and native CPU support, while the job step runs on a high-performance runner with minimal network overhead. This combination results in drastically reduced build and run times, improving developer feedback loops and reducing infrastructure costs.
Conclusion
Running GitHub Actions jobs in containers offers a powerful mechanism for achieving environment consistency, simplifying dependency management, and enhancing build reproducibility. By decoupling the execution environment from the runner OS, developers can ensure that their CI/CD pipelines reflect their production environments with high fidelity. The ability to authenticate with private registries and mount volumes further expands the utility of this approach for enterprise use cases.
However, the performance benefits of containerized jobs are only fully realized when network overhead is minimized. Traditional approaches that rely on pulling images from remote registries can introduce significant latency. The integration of specialized tools like Depot introduces ephemeral registries and accelerated build engines that operate on the same network as the runners. This architectural alignment eliminates network transfer costs, leverages persistent layer caching, and utilizes optimized compute resources. By combining these technologies, organizations can achieve up to 40x faster builds and 30% faster compute performance, all at a lower cost. As CI/CD pipelines grow in complexity, the shift toward containerized, network-optimized workflows will become increasingly critical for maintaining efficient, scalable, and reliable software delivery processes.