GitLab CI/CD Specialist cheat sheet

A .gitlab-ci.yml must contain at least one job; a top-level key that is not a reserved keyword and not a job name causes a pipeline creation error.

Reserved top-level keywords include stages, variables, default, include, workflow, image, services, cache, before_script, after_script, and pages; any other key is treated as a job name.

include supports local, remote, template, and project sources; include:project requires include:file or include:ref, and nested includes are capped (default max depth 100).

extends performs a reverse deep merge: the child overrides scalars, arrays are replaced rather than concatenated, and up to 11 levels of inheritance are allowed.

YAML anchors (&name / *name) and !reference tags deduplicate config; !reference can pull a single key out of another job, including nested keys.

default: sets image, services, cache, before_script, after_script, tags, and retry for all jobs; a job-level definition replaces the default rather than merging.

script is the only required job keyword; before_script and after_script run per job, and after_script runs in a separate shell so exported variables and cwd do not persist.

Global workflow:rules gates whether a pipeline is created at all; job-level rules only gate whether a given job is added.

Executor choice determines isolation: shell runs directly on the host, docker runs each job in a container, kubernetes runs each job in a pod, and docker-autoscaler provisions ephemeral containers.

A runner's config.toml holds concurrent (global parallelism), [[runners]] entries with url, token, executor, and [runners.docker] settings such as image, privileged, and volumes.

Runner registration tokens are deprecated in favor of runner authentication tokens created in the UI/API; the token is stored in config.toml and identifies the runner, not the user.

Job tags are matched against runner tags; a job whose tags match no available runner stays pending with 'no runners that can run this job'.

tags on a job is an AND filter over the runner's tag set; the special tag docker is not implicit and must be assigned explicitly.

Protected runners only accept jobs on protected branches or protected tags; unprotected runners accept any job, so secrets should be paired with protected runners.

image and services are ignored by the shell executor; the shell executor uses software installed on the runner host and inherits its environment.

concurrent on the runner and resource_group on the job both limit parallelism, but only resource_group serializes jobs across runners for the same deployment target.

Precedence, highest to lowest: trigger/manual pipeline variables, project variables, group variables, instance variables, then .gitlab-ci.yml job-level, then global YAML, then deployment variables.

A variable marked protected is only exposed to pipelines on protected branches or tags; a variable marked masked must meet masking rules (min 8 chars, no whitespace, Base64/hex-safe charset).

Masked variables are redacted in job logs; masking is a log filter, not encryption, so a transformed value (e.g. base64-encoded) is not automatically masked.

variables: values are strings; booleans and numbers should be quoted, and $VAR in a value is expanded at runtime unless escaped with $$.

File-type variables write the value to a temporary file and set the variable to that path; use them for kubeconfig, certificates, and SSH keys.

CI/CD secrets from external managers (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) are integrated via secrets: with vault:, azure_key_vault:, or gcp_secret_manager: providers.

id_tokens issues an OIDC JWT scoped to the job's aud claim; it is the supported way to authenticate to cloud providers without storing long-lived credentials.

Predefined variables such as CI_COMMIT_REF_PROTECTED, CI_PIPELINE_SOURCE, CI_JOB_TOKEN, and CI_REGISTRY_PASSWORD are read-only and cannot be overridden in YAML.

Cache is a best-effort optimization stored on the runner (local, S3, GCS, Azure); artifacts are uploaded to GitLab and are guaranteed to be passed to later stages.

Cache key should include a lockfile hash (e.g. key: files: [package-lock.json]) so dependency changes invalidate the cache; a static key risks stale dependencies.

cache:key:files computes a SHA over the listed files, and cache:key:prefix combines that SHA with a literal string.

Artifacts support paths, exclude, expire_in, when (on_success, on_failure, always), and reports: for JUnit, coverage, SAST, and dependency scanning.

dependencies restricts which prior jobs' artifacts a job downloads; without it, a job downloads artifacts from all jobs in earlier stages.

parallel: N creates N jobs with CI_NODE_INDEX and CI_NODE_TOTAL; parallel:matrix expands over named dimensions and produces one job per combination.

needs builds a DAG that ignores stage order; jobs with needs start as soon as their dependencies finish, and needs: [] starts a job immediately.

interruptible: true lets a new pipeline cancel the running job when auto-cancel redundancies is enabled; resource_group serializes jobs that touch the same environment.

Stages run in the order declared in stages; jobs in the same stage run in parallel, and a failing job blocks later stages unless allow_failure: true or when: manual.

rules are evaluated top to bottom; the first matching rule wins, and when: never in that rule excludes the job. only/except are legacy and cannot be mixed with rules in the same job.

rules:changes compares against the previous commit on branches and against the target branch on merge requests; it is always true on new branches and scheduled pipelines.

rules:if supports CI_PIPELINE_SOURCE, CI_COMMIT_BRANCH, CI_COMMIT_TAG, CI_MERGE_REQUEST_* variables; use $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH for default-branch gating.

when values are on_success, on_failure, always, manual, delayed, and never; when: delayed requires start_in (e.g. start_in: 30 minutes).

trigger starts a downstream pipeline, either as a multi-project pipeline (with project and branch) or a child pipeline (with include); child pipelines appear in the parent's pipeline graph.

strategy: depend on a trigger makes the parent job status mirror the downstream pipeline; without it the parent succeeds when the trigger is created.

environment with action: stop and on_stop defines a teardown job; environments track deployments and enable review apps and rollback.

Protected environments restrict who can deploy and require approval rules; deployment jobs targeting them must run on protected branches to access protected variables.

CI_JOB_TOKEN grants limited API access scoped to the project's allowlist; it is short-lived and should not be confused with a personal or project access token.

Secret detection, SAST, dependency scanning, container scanning, and license scanning are configured via include: template or the Security Configuration UI and publish reports under artifacts:reports.

allow_failure: exit_codes lets specific exit codes pass a job, which is how security scanners report findings without failing the pipeline.

Common failure: 'This job is stuck because no runners online' means tag mismatch, runner paused, or protected-runner/branch mismatch - check runner tags and CI_COMMIT_REF_PROTECTED.

Common failure: YAML invalid - use CI Lint (/ci/lint) or the API /projects/:id/ci/lint; a leading tab, duplicate key, or unresolvable !reference breaks the whole pipeline.

Job logs are capped (default 4 MB per job trace); increase ci_jobs_trace_size_limit or reduce verbosity, since truncated logs hide the real error.

retry accepts max and when (always, unknown_failure, script_failure, runner_system_failure, stuck_or_timeout_failure) to auto-retry flaky infrastructure failures.