Modern applications often behave differently across development, testing, and production environments. A project may work correctly on a developer’s computer but fail inside a CI server because the operating system, runtime, dependencies, or configuration differs.
Docker helps solve this problem by packaging an application and its required environment into a portable container image.
When Docker works with CI/CD, development teams can automatically build, test, scan, publish, and deploy the same application image. As a result, the delivery process becomes more consistent and repeatable.
This complete guide explains how CI/CD with Docker works, what tools it requires, how to write a Dockerfile, how to build and tag images, and how to create practical pipelines with GitHub Actions, GitLab CI/CD, and Jenkins.
What Is CI/CD?
CI/CD stands for:
- CI: Continuous Integration
- CD: Continuous Delivery or Continuous Deployment
These practices automate the process of moving code from development to production.
Continuous Integration
Continuous Integration allows developers to merge small code changes into a shared repository regularly.
Whenever a developer pushes code, the CI pipeline can:
- Download the source code
- Install project dependencies
- Check code quality
- Run automated tests
- Build the application
- Report the result
This process helps teams detect errors before merging or deploying the code.
Continuous Delivery
Continuous Delivery automatically prepares a tested build for release.
The pipeline may deploy the application to a staging environment. However, a person usually approves the final production deployment.
Continuous Deployment
Continuous Deployment automatically releases every successful change to production.
This approach provides faster releases. Nevertheless, it requires reliable tests, secure credentials, production monitoring, and an effective rollback strategy.
What Is Docker?
Docker is a platform for building, packaging, distributing, and running applications inside containers.
A container includes the application and the files it needs at runtime. Therefore, the application can run consistently across different environments.
Docker commonly uses:
- Dockerfile: Instructions for building an image
- Docker image: An immutable application package
- Docker container: A running instance of an image
- Docker registry: A service that stores and distributes images
- Docker Compose: A tool for defining multi-container applications
- Docker Buildx: An extended Docker build tool
- BuildKit: Docker’s modern build engine
Docker does not replace CI/CD. Instead, Docker provides a consistent application package and execution environment that a CI/CD pipeline can use.
What Is CI/CD with Docker?
CI/CD with Docker is an automated software-delivery process that uses Docker containers and images during integration, testing, building, and deployment.
Docker may perform two different roles inside a pipeline.
Docker as a Build Environment
The pipeline runs commands inside a container that contains the required development tools.
For example, a Node.js project can run tests inside a Node container:
docker run --rm \
-v "$PWD:/app" \
-w /app \
node:22 \
npm test
This approach provides a predictable Node.js environment even if the CI runner does not have Node.js installed directly.
Docker as the Application Package
The pipeline builds the application into a Docker image.
For example:
docker build -t my-app:1.0.0 .
Next, the pipeline tests, scans, pushes, and deploys that image.
Docker’s official CI documentation explains that containers provide isolated and reproducible build environments. A Dockerfile can define the operating system, runtime, binaries, and other requirements used during the build.
Why Use Docker in CI/CD?
Docker offers several benefits when combined with CI/CD.
Consistent Environments
Developers, testing servers, staging systems, and production servers can use the same image.
This consistency reduces the common problem:
“It works on my machine, but it fails in production.”
Reproducible Builds
The Dockerfile records the environment and build instructions. Therefore, the pipeline can recreate the application image whenever required.
Isolated Pipeline Jobs
A container separates one pipeline’s processes and dependencies from other jobs.
For example, two projects can use different Node.js versions without changing the CI runner’s global installation.
Portable Application Packages
A Docker image can run on a laptop, server, cloud platform, container service, or Kubernetes cluster with a compatible container runtime.
Faster Environment Setup
The pipeline can download a prepared image instead of installing every tool from the beginning.
Easier Rollback
Teams can keep previous image versions in a registry.
If a new release fails, the deployment system can restore an earlier image tag or, more reliably, a known image digest.
Better Scaling
Container platforms can create multiple application instances from the same image.
Improved Testing
Integration tests can start temporary containers for databases, caches, message brokers, and other services.
Infrastructure Flexibility
Teams can run containerized applications on:
- Virtual machines
- Docker hosts
- Kubernetes
- Amazon ECS
- Azure Container Apps
- Google Cloud Run
- Other container platforms
Important Docker CI/CD Concepts
Before creating a pipeline, you should understand several core concepts.
Dockerfile
A Dockerfile contains the instructions Docker uses to build an image.
Example:
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
Each instruction contributes to the final image or its configuration.
Docker Image
A Docker image is a read-only package that contains the application, runtime, dependencies, and configuration required to start a container.
Images consist of reusable layers.
Docker Container
A container is a running instance of an image.
You can start one with:
docker run my-app:1.0.0
An image is the package, while a container is the running process created from that package.
Docker Registry
A registry stores and distributes Docker images.
Popular registries include:
- Docker Hub
- GitHub Container Registry
- GitLab Container Registry
- Amazon Elastic Container Registry
- Google Artifact Registry
- Azure Container Registry
- JFrog Artifactory
- Sonatype Nexus
Repository
A registry repository stores related image versions.
For example:
registry.example.com/team/payment-api
The same repository may contain multiple tags.
Image Tag
A tag provides a human-readable name for an image version.
Examples include:
my-app:1.0.0
my-app:staging
my-app:production
my-app:latest
Tags are convenient, but they can change to point to another image.
Image Digest
A digest identifies image content through an immutable cryptographic value.
Example:
my-app@sha256:abc123...
Unlike a mutable tag, a digest points to exact image content.
Build Context
The build context is the collection of files Docker can access during a build.
This command uses the current directory as its context:
docker build -t my-app:1.0.0 .
The final dot represents the current directory.
Layer
Docker creates image layers from Dockerfile instructions.
If a layer has not changed, Docker may reuse it from the build cache.
Build Cache
The build cache stores reusable results from previous builds.
An effective cache can greatly reduce pipeline duration.
Container Registry Credentials
The CI/CD pipeline needs credentials before it can push an image to a private registry.
Store these credentials in the CI platform’s secret-management system.
How Does a Docker CI/CD Pipeline Work?
A Docker-based pipeline normally follows these stages.
Stage 1: Developer Pushes Code
A developer changes the application and pushes the update to a Git repository.
The update may target:
- A feature branch
- A development branch
- The main branch
- A release branch
- A Git tag
Stage 2: CI/CD Platform Starts the Pipeline
A repository event triggers the workflow.
Common CI/CD platforms include:
- GitHub Actions
- GitLab CI/CD
- Jenkins
- Azure Pipelines
- CircleCI
- Bitbucket Pipelines
Stage 3: Source Code Checkout
The CI runner downloads the repository and checks out the requested commit.
Stage 4: Code Quality and Unit Tests
The pipeline can run formatting, linting, static analysis, and unit tests before creating the production image.
Running fast checks early provides quicker feedback.
Stage 5: Docker Image Build
The pipeline reads the Dockerfile and builds the image.
docker build -t my-app:test .
Stage 6: Container Testing
The pipeline starts a container from the newly built image.
docker run --rm my-app:test npm test
The workflow may also perform health checks or send requests to the running service.
Stage 7: Security Scanning
A security tool examines the image for vulnerable operating-system packages, libraries, secrets, and misconfigurations.
Stage 8: Image Tagging
The pipeline assigns useful tags.
For example:
docker tag my-app:test registry.example.com/team/my-app:1.4.0
docker tag my-app:test registry.example.com/team/my-app:abc1234
A commit-based tag connects the image to its source-code version.
Stage 9: Registry Authentication
The pipeline signs in to the registry using securely stored credentials.
echo "$REGISTRY_PASSWORD" | docker login \
--username "$REGISTRY_USERNAME" \
--password-stdin registry.example.com
Stage 10: Image Push
The pipeline uploads the image:
docker push registry.example.com/team/my-app:1.4.0
Stage 11: Deployment
The deployment system downloads the approved image and creates new containers.
Stage 12: Verification and Monitoring
After deployment, the pipeline or monitoring system checks:
- Container health
- HTTP responses
- Application errors
- CPU and memory use
- Deployment status
- Logs
- User-facing behavior
If verification fails, the system can restore the previous version.
Creating a Dockerfile for CI/CD
Consider a simple Node.js application with this structure:
my-app/
├── src/
│ └── server.js
├── tests/
├── package.json
├── package-lock.json
├── Dockerfile
├── .dockerignore
└── README.md
A basic Dockerfile may look like this:
# syntax=docker/dockerfile:1
FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY src ./src
ENV NODE_ENV=production
EXPOSE 3000
USER node
CMD ["node", "src/server.js"]
Let us understand each instruction.
FROM
FROM node:22-alpine
The FROM instruction selects the base image.
Choose a trusted, maintained, and appropriately small image.
WORKDIR
WORKDIR /app
This instruction sets the working directory for later commands.
COPY
COPY package.json package-lock.json ./
The COPY instruction adds files from the build context to the image.
Copying dependency files before application source files improves cache reuse.
RUN
RUN npm ci --omit=dev
The RUN instruction executes a command while building the image.
ENV
ENV NODE_ENV=production
This instruction sets a non-sensitive environment variable.
Never use it to store passwords or private tokens.
EXPOSE
EXPOSE 3000
EXPOSE documents the port on which the application listens. It does not automatically publish that port to the host.
USER
USER node
This instruction runs the application as the existing non-root node user.
CMD
CMD ["node", "src/server.js"]
CMD defines the default command for the container.
Using a .dockerignore File
A .dockerignore file prevents unnecessary files from entering the build context.
Example:
.git
.github
.gitlab-ci.yml
Jenkinsfile
node_modules
npm-debug.log
coverage
dist
.env
.env.*
README.md
Dockerfile*
docker-compose*.yml
The exact exclusions depend on your project.
A good .dockerignore file can:
- Reduce the build context
- Speed up builds
- Prevent local dependencies from entering the image
- Avoid copying Git history
- Lower the risk of including secret files
- Improve cache behavior
Docker recommends using .dockerignore to exclude files that the image does not need in its Dockerfile best-practices guide.
Do not rely only on .dockerignore for secret protection. Prevent sensitive files from entering the repository and use a proper secret-management system.
Multi-Stage Docker Builds
A multi-stage build uses more than one FROM instruction.
One stage builds the application, while another creates the final runtime image.
Example for a Node.js application:
# syntax=docker/dockerfile:1
FROM node:22-alpine AS dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
FROM dependencies AS test
COPY . .
RUN npm test
FROM dependencies AS build
COPY . .
RUN npm run build
FROM node:22-alpine AS production
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]
This Dockerfile creates separate dependency, test, build, and production stages.
The final image does not need to contain the complete build toolchain or test files.
Multi-stage builds can:
- Reduce final image size
- Separate testing from production
- Lower the runtime attack surface
- Prevent build tools from entering production
- Improve Dockerfile organization
Docker recommends multi-stage builds because they create a clearer separation between build output and the final runtime image.
Building and Testing Specific Stages
You can build the testing stage:
docker build --target test -t my-app:test .
If the tests fail, Docker returns an unsuccessful build result.
Next, build the production image:
docker build --target production -t my-app:production .
This method ensures that the Dockerfile describes both the test and production environments.
Running a Docker Container Locally
Build the image:
docker build -t my-app:local .
Start a container:
docker run --rm -p 3000:3000 my-app:local
The --rm option removes the stopped container automatically.
The -p option maps host port 3000 to container port 3000.
Test the application:
curl http://localhost:3000/health
Stop the container with Ctrl+C.
Local testing helps verify the Dockerfile before adding it to a CI/CD pipeline.
Docker Image Tagging Strategy
A good tagging strategy makes every build identifiable.
Useful tag types include:
Commit SHA Tag
my-app:a1b2c3d
This tag connects the image to a specific source-code commit.
Version Tag
my-app:2.4.1
Version tags work well for formal releases.
Environment Tag
my-app:staging
my-app:production
These tags communicate deployment intent. However, they usually move between images.
Branch Tag
my-app:develop
my-app:feature-login
Branch tags can support development environments. Ensure branch names become valid and safe image tags.
Latest Tag
my-app:latest
The latest tag is only a normal tag. Docker does not guarantee that it represents the newest secure or stable release.
For production, deploy a version tag or image digest instead of relying only on latest.
Recommended Image Tagging Example
Suppose the application version is 2.4.1, and the short commit SHA is a1b2c3d.
The pipeline can create:
registry.example.com/team/my-app:2.4.1
registry.example.com/team/my-app:a1b2c3d
Both tags may point to the same image.
The deployment system can then record the exact digest:
registry.example.com/team/my-app@sha256:...
This approach provides traceability and predictable rollback.
CI/CD with Docker Using GitHub Actions
The following example builds, tests, and pushes a Docker image to GitHub Container Registry.
Create:
.github/workflows/docker.yml
Add:
name: Docker CI/CD
on:
push:
branches:
- main
tags:
- "v*"
pull_request:
branches:
- main
permissions:
contents: read
packages: write
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Check out source code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GitHub Container Registry
if: github.event_name != 'pull_request'
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Generate image metadata
id: metadata
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=sha
type=ref,event=branch
type=ref,event=tag
- name: Build and test image
uses: docker/build-push-action@v6
with:
context: .
target: test
push: false
cache-from: type=gha
cache-to: type=gha,mode=max
- name: Build and push production image
if: github.event_name != 'pull_request'
uses: docker/build-push-action@v6
with:
context: .
target: production
push: true
tags: ${{ steps.metadata.outputs.tags }}
labels: ${{ steps.metadata.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
This workflow:
- Downloads the source code
- Configures Docker Buildx
- Authenticates with the registry
- Generates image tags and labels
- Builds the test stage
- Builds the production stage
- Pushes approved images
- Reuses build cache
Pull requests build and test the image but do not push it.
Production deployment should normally use a separate job with environment protection and appropriate approval rules.
CI/CD with Docker Using GitLab CI/CD
Create a .gitlab-ci.yml file:
stages:
- test
- build
- deploy
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: ""
IMAGE_SHA: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
default:
image: docker:cli
services:
- name: docker:dind
before_script:
- echo "$CI_REGISTRY_PASSWORD" |
docker login
--username "$CI_REGISTRY_USER"
--password-stdin
"$CI_REGISTRY"
test-image:
stage: test
script:
- docker build
--target test
--tag "$CI_REGISTRY_IMAGE:test-$CI_COMMIT_SHORT_SHA"
.
build-image:
stage: build
script:
- docker build
--target production
--tag "$IMAGE_SHA"
.
- docker push "$IMAGE_SHA"
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
deploy-staging:
stage: deploy
script:
- ./scripts/deploy.sh "$IMAGE_SHA" staging
environment:
name: staging
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
This example uses Docker-in-Docker, often called DinD.
The runner must support this setup and apply suitable security controls. Exact TLS and runner settings depend on the GitLab Runner configuration.
The pipeline:
- Builds the test target
- Builds a production image
- Tags the image with the commit SHA
- Pushes it to GitLab Container Registry
- Deploys the same image to staging
CI/CD with Docker Using Jenkins
A Jenkins Declarative Pipeline may look like this:
pipeline {
agent {
label 'docker'
}
options {
timestamps()
timeout(time: 30, unit: 'MINUTES')
disableConcurrentBuilds()
}
environment {
REGISTRY = 'registry.example.com'
IMAGE_REPOSITORY = 'team/my-app'
IMAGE_TAG = "${GIT_COMMIT}"
}
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Build Test Image') {
steps {
sh '''
docker build \
--target test \
--tag my-app:test .
'''
}
}
stage('Build Production Image') {
steps {
sh '''
docker build \
--target production \
--tag ${REGISTRY}/${IMAGE_REPOSITORY}:${IMAGE_TAG} .
'''
}
}
stage('Registry Login and Push') {
when {
branch 'main'
}
steps {
withCredentials([
usernamePassword(
credentialsId: 'container-registry',
usernameVariable: 'REGISTRY_USER',
passwordVariable: 'REGISTRY_PASSWORD'
)
]) {
sh '''
echo "$REGISTRY_PASSWORD" |
docker login "$REGISTRY" \
--username "$REGISTRY_USER" \
--password-stdin
docker push \
${REGISTRY}/${IMAGE_REPOSITORY}:${IMAGE_TAG}
'''
}
}
}
stage('Deploy Staging') {
when {
branch 'main'
}
steps {
sh '''
./scripts/deploy.sh \
${REGISTRY}/${IMAGE_REPOSITORY}:${IMAGE_TAG} \
staging
'''
}
}
}
post {
always {
sh 'docker logout "$REGISTRY" || true'
deleteDir()
}
success {
echo 'Docker CI/CD pipeline completed successfully'
}
failure {
echo 'Docker CI/CD pipeline failed'
}
}
}
The Jenkins agent needs Docker access and an appropriate security configuration.
Do not expose the Docker daemon carelessly. Access to a powerful Docker daemon can provide extensive control over its host.
Using Docker Compose in CI/CD
Docker Compose helps start multi-container environments.
A test environment may include:
- Application
- PostgreSQL
- Redis
- Message queue
Example compose.test.yml:
services:
app:
build:
context: .
target: test
environment:
DATABASE_URL: postgresql://test:test@database:5432/app_test
REDIS_URL: redis://cache:6379
depends_on:
database:
condition: service_healthy
cache:
condition: service_started
database:
image: postgres:17-alpine
environment:
POSTGRES_DB: app_test
POSTGRES_USER: test
POSTGRES_PASSWORD: test
healthcheck:
test:
- CMD-SHELL
- pg_isready -U test -d app_test
interval: 5s
timeout: 5s
retries: 10
cache:
image: redis:8-alpine
Run the test stack:
docker compose -f compose.test.yml up \
--build \
--abort-on-container-exit \
--exit-code-from app
Clean up afterward:
docker compose -f compose.test.yml down --volumes
Removing test volumes prevents data from one pipeline run from affecting another.
For real projects, pin and review service-image versions based on project compatibility rather than copying example versions without verification.
How Docker Build Cache Works in CI/CD
Docker processes Dockerfile instructions in order.
For each instruction, it checks whether a reusable result exists. If so, Docker can restore that result instead of executing the instruction again.
Suppose your Dockerfile contains:
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
If application code changes but the package files remain unchanged, Docker may reuse the dependency-installation layer.
However, this less efficient order causes more cache invalidation:
COPY . .
RUN npm ci
Any source-code change can invalidate the COPY layer and force npm ci to run again.
Docker’s build cache documentation explains cache behavior and optimization options.
BuildKit Cache Mount Example
BuildKit supports cache mounts for package-manager downloads.
Example:
# syntax=docker/dockerfile:1
FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci
COPY . .
RUN npm run build
The cache mount lets later builds reuse downloaded package data without storing the cache in the final image layer.
External Cache in CI/CD
Many CI runners are temporary. Their local Docker cache disappears after each job.
Buildx can export and import cache through:
- CI-platform cache
- Registry cache
- Local directory
- Cloud cache backend
Generic registry-cache example:
docker buildx build \
--cache-from type=registry,ref=registry.example.com/team/my-app:buildcache \
--cache-to type=registry,ref=registry.example.com/team/my-app:buildcache,mode=max \
--tag registry.example.com/team/my-app:a1b2c3d \
--push \
.
Protect the cache registry with suitable authentication and retention settings.
Handling Secrets Safely
CI/CD pipelines often require sensitive values such as:
- Registry passwords
- Private package tokens
- API keys
- SSH keys
- Cloud credentials
- Deployment tokens
- Signing certificates
Never add secrets directly to:
- Dockerfiles
- Docker images
- Git repositories
- Image tags
- Build arguments
- Public logs
Why Build Arguments Are Unsafe for Secrets
A command such as this may expose sensitive information through image metadata or build history:
ARG API_TOKEN
RUN npm config set //registry.example.com/:_authToken=$API_TOKEN
Do not use normal ARG or ENV instructions for private build credentials.
BuildKit Secret Mounts
Use BuildKit secret mounts when a build needs temporary access to a secret.
Dockerfile:
# syntax=docker/dockerfile:1
FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
npm ci
Build command:
docker build \
--secret id=npmrc,src="$HOME/.npmrc" \
-t my-app:secure .
The secret becomes available only during the selected build step and does not become a normal image layer.
Inside CI/CD, create the secret source from the platform’s protected secret storage.
Testing Docker Images in CI/CD
Building an image successfully does not prove that the application works.
A good pipeline should test the image.
Run Unit Tests During the Build
docker build --target test -t my-app:test .
Start the Production Image
docker run -d \
--name my-app-test \
-p 3000:3000 \
my-app:production
Wait for the Health Endpoint
for attempt in $(seq 1 30); do
if curl --fail http://localhost:3000/health; then
exit 0
fi
sleep 2
done
docker logs my-app-test
exit 1
Remove the Test Container
docker rm -f my-app-test
The exact health-check command depends on the application.
Additional image tests may verify:
- The application starts
- Required ports respond
- Runtime configuration works
- The process uses a non-root user
- Expected files exist
- Database connectivity works
- API requests return correct responses
- The container shuts down gracefully
Docker Image Security Scanning
Container images may contain vulnerable:
- Operating-system packages
- Language dependencies
- Libraries
- Configuration files
- Embedded secrets
A CI/CD pipeline can scan images before pushing or deploying them.
Popular scanning options include:
- Docker Scout
- Trivy
- Grype
- Snyk
- Cloud registry scanners
Example with Trivy:
trivy image \
--exit-code 1 \
--severity HIGH,CRITICAL \
registry.example.com/team/my-app:a1b2c3d
An exit code of 1 can fail the pipeline when matching vulnerabilities appear.
However, teams should define practical policies. Some findings may lack a fix, belong to unused components, or require additional investigation.
Software Bill of Materials
A Software Bill of Materials, or SBOM, lists components inside an application or image.
It can help teams:
- Identify dependencies
- Investigate vulnerabilities
- Meet compliance requirements
- Improve supply-chain visibility
- Respond to security incidents
Depending on the selected tools, the pipeline can generate an SBOM and attach or publish it with the image.
Image Signing and Provenance
An advanced supply-chain workflow may sign container images and produce build provenance.
These features help consumers verify:
- Who produced the image
- Which workflow created it
- Which source revision it represents
- Whether someone changed it
- Which build process generated it
Signing does not make vulnerable software safe. However, it improves trust and traceability.
Deploying Docker Images
After the pipeline pushes an image, the deployment environment pulls and runs it.
Deployment to a Docker Server
A simple server deployment may use:
docker pull registry.example.com/team/my-app:a1b2c3d
docker stop my-app || true
docker rm my-app || true
docker run -d \
--name my-app \
--restart unless-stopped \
-p 80:3000 \
--env-file /secure/path/production.env \
registry.example.com/team/my-app:a1b2c3d
This example is simple, but replacing a container directly may create downtime.
Production systems often use an orchestrator, reverse proxy, rolling deployment, or blue-green strategy.
Deployment with Docker Compose
A production Compose file may reference a published image:
services:
app:
image: registry.example.com/team/my-app:${IMAGE_TAG}
restart: unless-stopped
env_file:
- /secure/path/production.env
ports:
- "80:3000"
Deploy:
IMAGE_TAG=a1b2c3d docker compose up -d
Deployment to Kubernetes
A pipeline can update a Kubernetes workload to use the new image.
However, Kubernetes configuration, rollout strategy, permissions, secrets, health checks, and rollback deserve a separate detailed guide.
Deployment Strategies for Docker Containers
Different deployment strategies provide different balances of speed and safety.
Recreate Deployment
The old container stops before the new one starts.
This method is simple but may create downtime.
Rolling Deployment
The platform gradually replaces old containers with new ones.
Users can continue accessing the application during the rollout when the system has enough healthy replicas.
Blue-Green Deployment
Two environments exist:
- Blue: Current production version
- Green: New version
The team tests the green environment before directing traffic to it.
If the release fails, traffic can return to blue.
Canary Deployment
A small percentage of traffic reaches the new version first.
The team monitors errors and performance before expanding the release.
Rollback Strategy
A rollback restores a previous working image.
Suppose the current release uses:
my-app:2.5.0
The previous stable version uses:
my-app:2.4.1
A rollback can redeploy 2.4.1.
For better accuracy, record and redeploy the previous digest.
A reliable rollback plan should include:
- Previous image digest
- Deployment configuration
- Environment settings
- Database compatibility
- Rollback commands
- Approval process
- Health verification
Database changes can make rollback difficult. Use backward-compatible migrations whenever possible.
Docker-in-Docker Explained
Docker-in-Docker means that a containerized CI environment runs Docker builds.
A common setup starts a Docker daemon as a separate service and connects the job container to it.
Benefits include:
- Isolated build setup
- Easy CI configuration
- A standard Docker environment
However, risks and limitations may include:
- Privileged-container requirements
- Increased security exposure
- Cache complexity
- Storage management
- Networking confusion
- Performance overhead
Another approach connects the CI job to an existing Docker daemon through its socket. This method also carries major security implications because the job may gain extensive control over the Docker host.
Choose an approach based on the CI platform, threat model, runner isolation, and infrastructure requirements.
Common CI/CD with Docker Mistakes
Using Only the latest Tag
A deployment that uses only latest makes it difficult to identify and restore a specific build.
Use immutable identifiers such as commit tags and digests.
Rebuilding During Deployment
Do not build one image in testing and create another image for production.
Build once, test that image, and promote the same image.
Copying the Entire Repository Too Early
An early COPY . . instruction may invalidate the cache after every source-code change.
Copy dependency files first.
Including Secrets in the Image
Secrets can remain inside image layers even after a later instruction removes them.
Use secret mounts and runtime secret injection.
Running as Root
Containers often use root by default.
When the application allows it, switch to a non-root user.
Creating Large Images
Large images take longer to build, scan, upload, download, and start.
Use multi-stage builds and include only required runtime files.
Ignoring .dockerignore
An unnecessarily large build context slows the pipeline and may include sensitive or irrelevant files.
Skipping Image Tests
A successful build does not guarantee a working container.
Start and test the image before publishing or deploying it.
Ignoring Vulnerability Scans
Base images and application dependencies may contain known vulnerabilities.
Add security scanning to the workflow.
Using Untrusted Base Images
Choose trusted and maintained images. Review their source, update policy, and security posture.
Leaving Temporary Containers Running
Failed pipelines may leave containers, networks, and volumes behind.
Add reliable cleanup steps.
Giving Every Branch Registry Access
Untrusted branches and pull requests should not automatically receive production credentials.
Apply protected branches, environments, and secret-access rules.
Docker CI/CD Best Practices
Use Multi-Stage Builds
Keep build tools and test dependencies out of the final image.
Choose Trusted Base Images
Prefer Docker Official Images or other verified and trusted sources where appropriate.
Keep Images Small
Install only the packages the application needs.
Pin Versions Thoughtfully
Version tags improve predictability. Digests provide stronger immutability.
However, pinned dependencies still require regular updates to receive security fixes.
Build and Test in CI
Every relevant code change should automatically build and test the image.
Build Once and Promote
Use the same tested image across staging and production.
Tag Every Image Clearly
Include a commit SHA, release version, or another traceable identifier.
Use a .dockerignore File
Keep the build context small and clean.
Protect Registry Credentials
Store credentials in the CI platform’s secret system.
Use BuildKit Secrets
Do not pass sensitive build credentials through ARG or ENV.
Run as a Non-Root User
Reduce container privileges where possible.
Scan Before Deployment
Check images for known vulnerabilities and configuration problems.
Add Health Checks
Confirm that the application is ready before sending traffic.
Automate Cleanup
Remove temporary containers, networks, and volumes after tests.
Configure Cache Carefully
Use external caches for short-lived CI runners, but do not let stale caches hide dependency problems.
Rebuild Images Regularly
A source-code repository may remain unchanged while base images and dependencies receive security updates.
Keep a Rollback Version
Never remove the last known working image before confirming the new deployment.
CI/CD with Docker vs CI/CD Without Docker
| Feature | Without Docker | With Docker |
|---|---|---|
| Environment setup | Installed on runner | Defined through images |
| Dependency consistency | Can vary | Usually more consistent |
| Application packaging | Platform-specific | Container image |
| Local and CI similarity | Often lower | Usually higher |
| Isolation | Depends on runner | Container-level isolation |
| Rollback | Depends on package process | Previous image can be redeployed |
| Build complexity | May be simpler initially | Requires Docker knowledge |
| Image registry | Not required | Normally required |
| Runtime portability | Depends on application | Strong across compatible platforms |
| Security responsibilities | Host and application | Host, Docker, image, and application |
Docker adds useful consistency, but it also introduces image maintenance, registry access, scanning, and container-security responsibilities.
Frequently Asked Questions
Is Docker required for CI/CD?
No. Teams can build and deploy applications without Docker. However, Docker can provide consistent environments and portable deployment packages.
Can CI/CD run inside Docker?
Yes. A CI job can run inside a Docker container. Some CI platforms also allow service containers for databases and other dependencies.
What is a Docker image in CI/CD?
A Docker image is the packaged application that the pipeline builds, tests, stores, and deploys.
Where should CI/CD store Docker images?
Store images in a container registry such as Docker Hub, GitHub Container Registry, GitLab Container Registry, Amazon ECR, Google Artifact Registry, or Azure Container Registry.
Should every commit create a Docker image?
Every relevant commit may build an image for testing. However, the pipeline does not need to push every temporary image to the permanent registry.
Should pull requests push images?
Usually, pull requests only build and test images. Pushing may be useful for preview environments, but it requires safe naming, permissions, cleanup, and secret controls.
Should production use the latest tag?
Avoid relying only on latest. Use a version, commit SHA, or immutable digest.
What is Docker-in-Docker?
Docker-in-Docker is a setup in which a containerized build environment can execute Docker builds, usually by connecting to a Docker daemon service.
What is the difference between an image and a container?
An image is an immutable package. A container is a running instance created from that image.
What is the difference between an artifact and a Docker image?
A general artifact may be an APK, JAR, ZIP, report, or compiled website. A Docker image includes filesystem layers and runtime configuration for starting containers.
Can Docker build mobile applications?
A suitable Docker environment can build some mobile targets, especially Android. However, iOS builds still require Apple-supported macOS and Xcode environments.
Can Docker Compose run integration tests?
Yes. Docker Compose can start an application with databases, caches, queues, and other dependent services for testing.
How can I make Docker builds faster?
Use an effective .dockerignore, order Dockerfile instructions for cache reuse, use BuildKit cache mounts, export an external CI cache, and avoid unnecessary files and packages.
How do I keep Docker secrets secure?
Store secrets in the CI platform, use BuildKit secret mounts during builds, and inject runtime secrets through a secure deployment system.
Conclusion
CI/CD with Docker creates a consistent path from source code to production.
A developer pushes code to a Git repository. The CI/CD platform checks out that code, runs quality checks, builds a Docker image, executes tests, scans the image, and assigns traceable tags. Next, the pipeline pushes the approved image to a container registry and deploys the same image to staging or production.
Docker reduces environment differences by packaging the application and its runtime requirements together. Meanwhile, CI/CD automates the checks and actions required to deliver that package safely.
Start with a small workflow. First, create a Dockerfile and confirm that the application runs locally. Next, add a CI job that builds and tests the image. After that, configure registry authentication and image tags. Finally, introduce security scanning, protected deployment, health checks, monitoring, and rollback support.
A well-designed Docker CI/CD pipeline helps teams release applications faster while improving consistency, traceability, and reliability.
