GitLab CI/CD Docker Build Pipeline: Build and Push Images

A container build pipeline converts a reviewed source revision and Dockerfile into an immutable image, verifies it, and publishes it to an approved registry. The strongest design builds once and promotes the same digest through environments instead of rebuilding production from changing inputs.

Pipeline flow#

1. Validate application code and the Dockerfile.
2. Authenticate to the registry with short-lived or job-scoped credentials.
3. Build from pinned, trusted base-image references.
4. Tag the image with a unique commit-based identifier.
5. Run tests and security checks against the built image.
6. Push the image and capture its immutable digest.
7. Promote or deploy by digest after required approvals.

Choose a build approach#

Tagging strategy#

Use an immutable commit identifier or release version for traceability. A moving tag can provide convenience, but deployment records should retain the digest. Prevent untrusted branches from overwriting release tags.

Registry authentication#

Use GitLab-provided job credentials or another short-lived identity where supported. Limit push access to required repositories, protect release paths, avoid printing login commands with secrets, and ensure credentials are unavailable to untrusted merge-request jobs.

Build security#

• Pin base images by digest for controlled releases.
• Use minimal base images and a non-root runtime user.
• Keep secrets out of build arguments and image layers.
• Generate a software bill of materials.
• Scan dependencies and the final image.
• Sign or attest trusted releases.
• Block critical findings according to an exception process.

Caching without losing reproducibility#

Layer and registry caching can shorten builds, but cache keys and access must separate trust boundaries. The pipeline should remain correct when cache is unavailable, and protected builds should not restore executable cache content from untrusted sources.

Release verification#

Record source revision, pipeline, builder identity, image digest, scan result, and approval. Test pulling from the target environment and run the container with its intended non-root user, filesystem settings, health checks, and resource limits.

GitLab container registry documentation