Deploy to Kubernetes with GitLab CI/CD

A GitLab-to-Kubernetes deployment should promote a verified image into a protected environment using a narrowly scoped identity. The pipeline must confirm rollout health and preserve enough evidence to identify exactly what was deployed, by whom, and from which commit.

Deployment prerequisites#

• A tested image exists in an approved registry under an immutable digest.
• Kubernetes manifests or a packaging layer are version controlled.
• The deployment identity is limited to required namespaces and resources.
• Production environments and branches are protected.
• Readiness, liveness, startup, and resource settings are defined.
• Rollback and database compatibility have been planned.

Identity and cluster access#

Prefer short-lived workload identity or an agent-based connection over long-lived administrative kubeconfig data. If a credential file is unavoidable, scope it tightly, protect the variable, restrict runner access, and rotate it regularly. Never grant cluster-admin to routine deployment jobs.

Safe deployment flow#

1. Resolve the approved image digest.
2. Render and validate the intended manifests.
3. Run policy and security checks.
4. Record a diff against the current cluster state.
5. Require approval for sensitive environments.
6. Apply the change with the scoped identity.
7. Wait for rollout status and health checks.
8. Run a bounded smoke test.
9. Record the release and notify owners.

GitLab environments#

Environments provide deployment history and status. Use environment protection to control who can deploy, define clear staging and production boundaries, and avoid using a single credential across unrelated environments.

Rollout and rollback#

Common mistakes#

• Deploying a moving image tag without recording the digest.
• Giving the CI identity broad cluster permissions.
• Running production deployment on shared untrusted runners.
• Treating a successful apply command as proof of application health.
• Retrying after timeout without checking whether the first action succeeded.
• Changing application and irreversible schema behavior without coordinated rollback.

GitLab Kubernetes integration documentation