gitlab-cicd

name

gitlab-cicd

description

GitLab CI/CD pipeline expert for creating and configuring `.gitlab-ci.yml` files. Use when working with GitLab pipelines for: (1) Creating or editing `.gitlab-ci.yml` pipeline configurations, (2) Configuring jobs, stages, rules, `needs`, and includes, (3) Setting up CI/CD variables (masked, protected, external secrets), (4) Configuring caching and artifacts, (5) Setting up pipeline triggers, schedules, child/multi-project pipelines, (6) Runner configuration and image handling, (7) Security scanning integration (SAST, secret detection, dependency scanning), (8) Pipeline speed optimization and best practices, (9) Troubleshooting pipeline failures.

GitLab CI/CD

Quick Start

Minimum viable .gitlab-ci.yml:

stages: [build, test, deploy]

default:
  image: node:20-alpine
  before_script: [npm ci]

build:
  stage: build
  script: npm run build
  artifacts:
    paths: [dist/]
    expire_in: 1 week

test:
  stage: test
  needs: [build]
  script: npm test
  artifacts:
    reports:
      junit: junit.xml

deploy:
  stage: deploy
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
  environment:
    name: production
    url: https://example.com

---

Key Concepts

• Stages define execution order; jobs within a stage run in parallel
• needs: breaks stage ordering — use it for DAG execution (jobs run as soon as their deps finish)
• rules: controls when a job is included (preferred over deprecated only:/except:)
• default: sets defaults for all jobs (never put image:, cache:, etc. at top level — deprecated)
• .pre / .post are reserved stages that always run first/last

---

Reference Files

Load these as needed based on the task:

references/pipeline-config.md

Full .gitlab-ci.yml syntax reference: global keywords, job keywords, rules, needs, include, child/multi-project pipelines, parameterized components, and predefined variables.

Read when: Creating or editing pipeline config, working with needs/DAG pipelines, using include:, configuring parallel matrix jobs, or looking up predefined variable names.

references/variables.md

CI/CD variables: types (variable vs. file), defining in YAML and UI, precedence order, masking/protecting variables, external secrets (Vault/GCP/Azure/AWS), and caveats.

Read when: Working with CI/CD variables, secrets, masked/protected variables, or external secret managers.

references/caching-artifacts.md

Caching (keys, policies, multiple caches, fallbacks) and artifacts (upload, download, access control, artifact reports for JUnit/coverage/SAST/dotenv).

Read when: Setting up dependency caching, configuring artifacts, passing data between jobs, or working with test/coverage reports.

references/runners.md

Runner types, executors (Docker vs. Shell vs. Kubernetes), image pull policies, Docker-in-Docker vs. Kaniko, private registries, runner registration, and security.

Read when: Configuring runner tags, setting up Docker image handling, working with private registries, or building/pushing Docker images in CI.

references/triggers-pipelines.md

Pipeline types (basic, DAG, MR, parent-child, multi-project), API triggers, trigger: keyword, scheduled pipelines, MR pipelines, skipping pipelines, and manual jobs.

Read when: Setting up pipeline triggers, scheduled pipelines, MR pipelines, child/multi-project pipelines, or debugging $CI_PIPELINE_SOURCE values.

references/security.md

Security scanning templates (SAST, secret detection, container scanning), variable protection patterns, runner hardening, container security (Kaniko, non-root), supply chain security (image pinning, integrity verification), and a security checklist.

Read when: Adding security scanning, hardening the pipeline, configuring protected environments, or reviewing security posture.

references/optimization.md

Pipeline speed optimization: DAG with needs:, interruptible/auto_cancel, file-based job skipping, caching patterns, Docker image optimization, parallelization (parallel: N and matrix), resource groups, and general best practices.

Read when: Improving pipeline speed, reducing CI costs, parallelizing test runs, or identifying bottlenecks.

---

Common Patterns

Prevent Duplicate Pipelines (branch + MR)

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

Run Job Only on Main Branch

deploy:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - when: never

Only Run When Relevant Files Change

test-backend:
  rules:
    - changes: [backend/**, requirements.txt]
    - when: never

Pass Data Between Jobs

build:
  script:
    - echo "IMAGE_TAG=$(git rev-parse --short HEAD)" >> build.env
  artifacts:
    reports:
      dotenv: build.env   # variables available in downstream jobs

deploy:
  needs: [build]
  script: deploy.sh $IMAGE_TAG  # IMAGE_TAG comes from dotenv report

Monorepo: Trigger Child Pipelines Per Service

trigger-api:
  trigger:
    include: api/.gitlab-ci.yml
    strategy: depend

trigger-web:
  trigger:
    include: web/.gitlab-ci.yml
    strategy: depend
  rules:
    - changes: [web/**]

Manual Production Deploy with Confirmation

deploy-production:
  when: manual
  manual_confirmation: "Deploy to PRODUCTION?"
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

---

Security Essentials

• Store secrets in masked + protected UI variables, never in .gitlab-ci.yml
• Use protected environments to gate production deployments by role
• Include Security/SAST.gitlab-ci.yml and Security/Secret-Detection.gitlab-ci.yml at minimum
• Prefer Kaniko over Docker-in-Docker (no privileged runner required)
• Pin image tags to specific versions (not :latest); use digest pinning for highest assurance
• Review .gitlab-ci.yml changes in MRs with CODEOWNERS + required approvals

Speed Essentials

• Use needs: to unlock DAG execution — biggest single speed win
• Mark build/test jobs interruptible: true with workflow.auto_cancel.on_new_commit: interruptible
• Use cache.key.files: [lockfile] for automatic cache invalidation
• Skip jobs with rules.changes: when unrelated files changed
• Set expire_in: on all artifacts; use when: on_failure for debugging-only artifacts