GitLab CI · Cheat sheet

GitLab CI/CD cheat sheet

GitLab CI cheat sheet: stages, rules, artifacts, OIDC secrets, environments, includes, and security scanning.

50 commands·8 sections·Updated Sep 26, 2026·By SecOpsLog

Pipeline basics

Beginner

stages: [build, test, deploy]: Declare the ordered stages.
build: stage: build script: [make]: A job: a name, a stage, and a script.
image: node:24: Container image the job runs in.
tags: [docker]: Route the job to runners with these tags.
before_script / after_script: Run before/after a job’s script (set in default: for all jobs).
default: image: alpine: Defaults inherited by all jobs.

Intermediate

rules: - if: '$CI_COMMIT_BRANCH == "main"': Run the job only on certain conditions.
rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event": Run the job in merge request pipelines.
rules: - changes: [src/**/*]: Run when matching files changed (always true on new branches, tags, schedules).
rules: - exists: [Dockerfile]: Run only when a file exists in the repository.
rules: - if: $CI_COMMIT_REF_PROTECTED == "true": Gate deploy jobs to protected branches and tags, where protected variables exist.
rules: - if: $CI_MERGE_REQUEST_ID when: manual: Gate a job behind a manual click.
workflow: rules: [...]: Decide whether the WHOLE pipeline runs.
workflow: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS when: never - if: $CI_COMMIT_BRANCH: Branch pipelines until an MR opens, then MR pipelines only: no duplicates.
only / except: Deprecated: use rules (kept for compatibility).

Intermediate

artifacts: paths: [dist/] expire_in: 1 week: Pass build output to later jobs.
artifacts: reports: junit: report.xml: Surface test/scan reports in the MR.
cache: key: $CI_COMMIT_REF_SLUG paths: [node_modules/]: Reuse deps across runs.
cache: key: files: [package-lock.json] paths: [.npm/]: Cache keyed on the lockfile: it changes only when dependencies do.
needs: [build]: Start as soon as a dependency finishes (DAG).
dependencies: [build]: Choose which jobs’ artifacts to download.
parallel: 5: Fan a job out into N instances.
parallel: matrix: - REGION: [us, eu]: Run a job across a value matrix.
interruptible: true: A newer pipeline on the same ref may cancel this job (fine for tests, not deploys).
retry: max: 2 when: [runner_system_failure, api_failure]: Retry infrastructure failures only, so flaky tests stay visible.
timeout: 30m: Job-level timeout; takes precedence over the project-wide setting.

Intermediate

variables: APP_ENV: prod: Define variables at pipeline or job scope.
$CI_COMMIT_SHA $CI_PIPELINE_ID: Built-in predefined variables.
id_tokens: GITLAB_OIDC_TOKEN: aud: https://gitlab.example.com: Mint an OIDC JWT for keyless cloud/Vault auth; aud must match the provider’s audience.
secrets: DB: vault: prod/db/pass@ops: Fetch a Vault secret as a file variable (Premium; auth via id_tokens).

Advanced

environment: name: production url: https://app.io: Track a deployment target.
environment: name: review/$CI_COMMIT_REF_SLUG on_stop: teardown: Dynamic review apps.
resource_group: production: Serialize deploys so they never overlap.
when: manual allow_failure: false: Require a human to trigger a prod deploy.

Advanced

include: - local: ci/build.yml: Pull in local/project/remote/template YAML.
include: - component: $CI_SERVER_FQDN/my-org/security-components/secret-detection@1.0.0 inputs: stage: test: Reuse a versioned CI/CD component with typed inputs.
extends: .base_job: Inherit and override a hidden template job.
.def: &anchor { image: node } job: { <<: *anchor }: YAML anchors to share config (extends: is usually clearer).
script: - !reference [.setup, script]: Reuse a snippet from another job.
trigger: include: child.yml: Child pipeline (use trigger:project for multi-project).
trigger: include: - artifact: generated-config.yml job: generate-config: Dynamic child pipeline from YAML an earlier job generated.
spec: inputs: stage: default: test ---: Component or template header: typed inputs, used as $[[ inputs.stage ]].

Advanced

include: - template: Jobs/SAST.gitlab-ci.yml: Add static application security testing.
- template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml: SBOM-based dependency scanning (old template is deprecated).
- template: Jobs/Secret-Detection.gitlab-ci.yml: Catch committed secrets.
- template: Jobs/Container-Scanning.gitlab-ci.yml: Scan built images.

Intermediate

glab ci lint: Validate .gitlab-ci.yml locally.Example output
✓ CI/CD YAML is valid!
glab ci status: Live status of the current pipeline.
glab ci trace: Stream a running job’s logs.
glab ci run: Trigger a pipeline from the terminal.

Found a technical issue on this page? Report it with the tool version you used and the behavior you saw. How resources are maintained.

Go deeper

Hands-on courses for GitLab CI