The core idea: the image is the artifact

In a Docker-centered pipeline, the thing that gets built, tested, and ultimately deployed is not a loose collection of files — it is a single, versioned container image. That image becomes the pipeline’s actual output, the same way a compiled binary or a packaged application might be in a more traditional build process.

Why this solves the “works on my machine” problem

Because the image bundles the application together with its exact runtime environment — language version, system libraries, installed dependencies — the environment used to test it in CI is not just similar to the environment it will run in later, it can be made functionally identical. This removes an entire category of failures that only show up because two environments quietly differed in some small way nobody accounted for.

Build once, promote everywhere

A well-designed Docker-based pipeline builds a single image early on, then reuses that exact same image through every later stage — testing, staging, production — rather than rebuilding a fresh image at each stage. This “build once, promote everywhere” principle is what actually delivers on the promise that what was tested is what gets deployed.

The relationship between these pieces is what gives the whole pipeline its integrity: the build stage produces one image, every later stage refers back to that exact same image by its specific tag, and nothing downstream ever silently swaps in a different build.

When a change is pushed to the project’s source repository, the CI system detects it and starts a new pipeline run on a runner. The build stage checks out the code and runs a Docker build using the project’s Dockerfile, producing a new image tagged in a way that uniquely identifies this specific run — often using the source commit’s identifier, so the image can always be traced back to the exact code that produced it.

How the CI runner gets the ability to build and run Docker itself

Because the runner needs to build images and start containers as part of the pipeline, it needs its own access to a Docker engine. This is commonly achieved either by giving the runner access to the host machine’s own Docker engine, or by running a separate, isolated Docker engine specifically for that pipeline job — an approach generally referred to as Docker-in-Docker. Each approach comes with different trade-offs around isolation and security, covered further in a later chapter.

How testing and promotion actually happen

Once the image is built, the test stage starts one or more containers from that exact image and runs the test suite inside them, capturing the results. If the tests pass, the pipeline pushes that same image to a registry under its permanent tag. Later stages — a staging deployment, a production deployment — pull that specific image by its exact tag rather than building anything new, which is what guarantees the artifact being deployed is truly identical to the one that was tested.

flowchart TD
    A["Developer pushes commit abc123"] --> B["CI pipeline triggers automatically"]
    B --> C["Build stage: docker build, tag image as app:abc123"]
    C --> D["Test stage: container started from app:abc123 runs test suite"]
    D --> E{"Tests pass?"}
    E -->|"No"| F["Pipeline fails, image not promoted further"]
    E -->|"Yes"| G["Image app:abc123 pushed to registry"]
    G --> H["Staging deployment pulls app:abc123 from registry"]
    H --> I["Staging verification passes"]
    I --> J["Production deployment pulls the same app:abc123"]
    J --> K["Production runs the exact image that was built and tested"]
    

Notice that the commit identifier travels with the image the entire way through the diagram. If a problem is ever discovered in production, tracing it back to the exact source code that produced that image is immediate — there is no ambiguity about which version of the code is actually running, because the image tag says so directly.

The trade-off in one sentence: Docker-based pipelines trade some added build infrastructure and security surface for a dramatic increase in confidence that what was tested is genuinely what gets deployed.

A CI runner that has full, unrestricted access to build and run Docker containers effectively has a great deal of power over the host it runs on, particularly in setups where the runner shares the host’s own Docker engine directly. If a malicious or compromised pipeline step can build and run arbitrary containers with elevated privileges, it can potentially reach far beyond the intended scope of that one pipeline job.

Beyond runner privileges, secrets used during the build (private registry credentials, internal package tokens) need to be injected carefully so they never end up baked into an image layer that gets pushed to a registry, and every image, once built, benefits from an automated vulnerability scan before it is trusted for deployment — catching known, fixable issues in dependencies before they ever reach production. Treating the pipeline itself as part of the application’s attack surface, not just a background convenience, is the mindset that keeps a Docker-based CI/CD setup genuinely safe.