GitLab CI/CD

GitLab CI/CD #

GitLab CI/CD is the pipeline system built into GitLab. It uses a .gitlab-ci.yml file to define stages, jobs, runners, artifacts, caches, variables, environments, and deployment workflows.

Overview #

GitLab CI/CD works especially well when teams use GitLab as a single DevOps platform for source control, merge requests, container registries, security scanning, issue tracking, and releases. Jobs are executed by GitLab runners, which can be shared, group-specific, project-specific, self-managed, or Kubernetes-based.

Best use cases #

  • Organizations already standardized on GitLab for repositories and merge requests.
  • End-to-end workflows that combine source control, CI, container registry, security scanning, and environments.
  • Teams that need clear pipeline stages, artifacts, protected variables, and deployment tracking.
  • Kubernetes deployments with GitLab agents, Helm, kubectl, or GitOps workflows.
  • Self-managed runners for private networks, compliance, or specialized build environments.

Minimal pipeline example # 

stages:
  - test
  - build

unit_tests:
  stage: test
  image: node:22
  script:
    - npm ci
    - npm test

build_image:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  script:
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" .
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Secrets handling #

  • Store secrets as CI/CD variables at project, group, or instance level according to required scope.
  • Mark sensitive variables as masked and protected when they should only run on protected branches or tags.
  • Use environment-scoped variables for staging, production, and other deployment targets.
  • Prefer workload identity or short-lived cloud credentials over static access keys.
  • Keep secrets out of artifacts, caches, job traces, and Docker build arguments when possible.

Deployment options #

  • Deploy directly with shell scripts, Helm, kubectl, Terraform, OpenTofu, Ansible, or cloud CLIs.
  • Use GitLab environments to track staging, review apps, production deployments, and rollback actions.
  • Build and push images to the GitLab container registry, then deploy them to Kubernetes or cloud services.
  • Use merge request pipelines and protected environments for approval-controlled production releases.
  • Pair GitLab CI with GitOps tools such as Argo CD or Flux for pull-based Kubernetes delivery.

Security considerations #

  • Separate trusted protected-branch pipelines from untrusted merge request pipelines.
  • Restrict privileged Docker-in-Docker jobs to runners that are isolated and intentionally configured for that risk.
  • Keep runners patched and scoped to projects or groups with similar trust levels.
  • Use protected variables, protected environments, required approvals, and least-privilege deploy tokens.
  • Add SAST, dependency scanning, secret detection, container scanning, IaC scanning, and license checks where appropriate.
  • DevSecOps — Shift security checks into GitLab merge requests and pipelines.
  • GitOps — Let GitLab CI build artifacts while GitOps reconciles deployments.
  • Kubernetes — Deploy images and manifests from GitLab pipelines to Kubernetes.
  • Infrastructure as Code — Validate and apply IaC from GitLab CI/CD.
  • CI/CD Security Best Practices — Standardize secure runner, variable, and artifact handling.