GitLab CI/CD Cheat Sheet
Reference for .gitlab-ci.yml syntax, stages, jobs, rules, and caching for GitLab's built-in CI/CD pipelines.
Basic Pipeline
Minimal .gitlab-ci.yml with build, test, deploy stages.
stages: - build - test - deploybuild-job: stage: build script: - echo "Building..." - make buildtest-job: stage: test script: - make testdeploy-job: stage: deploy script: - make deploy rules: - if: '$CI_COMMIT_BRANCH == "main"'
Rules & Caching
Conditional execution and dependency caching.
test-job: stage: test cache: key: ${CI_COMMIT_REF_SLUG} paths: - node_modules/ script: - npm ci - npm test rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: always - when: never
Predefined Variables
Common CI/CD variables available in every job.
- CI_COMMIT_SHA- Full SHA of the commit being built
- CI_COMMIT_REF_SLUG- URL/DNS-safe slug of the branch or tag name
- CI_PIPELINE_SOURCE- What triggered the pipeline (push, merge_request_event, schedule, etc.)
- CI_JOB_TOKEN- Token scoped to the job for authenticating to GitLab APIs/registries
- CI_PROJECT_DIR- Absolute path where the repository is checked out in the job
- CI_ENVIRONMENT_NAME- Name of the environment associated with a deployment job
Artifacts & Docker-in-Docker
Passing artifacts between stages and building images.
build-image: stage: build image: docker:24 services: - docker:24-dind script: - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA . - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA artifacts: paths: - dist/ expire_in: 1 week
Parent-Child Pipelines
Trigger a downstream pipeline defined in another file, keeping large configs modular.
deploy-infra: stage: deploy trigger: include: infra/.gitlab-ci.yml strategy: depend rules: - if: '$CI_COMMIT_BRANCH == "main"'deploy-cross-project: stage: deploy trigger: project: my-group/infra-project branch: main
Dynamically Generated Child Pipeline
Generate a pipeline YAML at runtime and trigger it as a child pipeline artifact.
generate-config: stage: build script: - ./scripts/generate-pipeline.sh > generated-config.yml artifacts: paths: - generated-config.ymltrigger-dynamic: stage: deploy trigger: include: - artifact: generated-config.yml job: generate-config strategy: depend
DAG Ordering & Parallel Matrix
Use needs to break stage ordering into a dependency graph, and parallel:matrix to fan out jobs.
unit-test: stage: test needs: [] script: npm run test:unitdeploy: stage: deploy needs: ['unit-test'] script: ./deploy.shbrowser-test: stage: test needs: [] parallel: matrix: - BROWSER: [chrome, firefox, safari] script: - npx playwright test --project=$BROWSER
Rules Keywords Reference
Conditions and modifiers available inside a job's rules: block.
- changes: [paths]- Only runs the job when matching files changed in the diff
- exists: [paths]- Runs the job only if the given paths exist in the repository
- allow_failure: true- Job can fail without blocking the pipeline from passing
- when: manual- Job appears as a manual play button instead of running automatically
- when: delayed / start_in- Delays job start by a fixed duration after it becomes eligible
- $CI_MERGE_REQUEST_ID- Set only in merge request pipelines, useful for MR-specific rules
- needs: [] combined with rules- Lets a job start immediately without waiting for earlier stages when its own rule matches
CI/CD Components & Auto-Stop Environments
Include a versioned reusable component and register a deployment environment that expires.
include: - component: gitlab.com/my-group/ci-components/[email protected] inputs: stage: testreview-app: stage: deploy script: ./deploy-review.sh environment: name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.review.example.com on_stop: stop-review auto_stop_in: 1 weekstop-review: stage: deploy script: ./teardown-review.sh when: manual environment: name: review/$CI_COMMIT_REF_SLUG action: stop
Use 'extends' with hidden jobs (prefixed with a dot, e.g. .base_job) to DRY up repeated configuration across similar jobs instead of copy-pasting script blocks.
