GitLab CI Keywords Cheat Sheet: Every .gitlab-ci.yml Keyword

A keyword-by-keyword reference for .gitlab-ci.yml job configuration.

The job, control-flow, and artifact keywords for GitLab pipelines.

Job keywords

Keyword	Purpose
script	Shell commands to run
before_script / after_script	Setup / teardown
stage	Which stage the job belongs to
image	Docker image
services	Linked containers
tags	Select runners by tag
variables	Job-level env vars

Control flow

Keyword	Purpose
rules	Conditional inclusion (replaces only/except)
needs	DAG dependencies (out-of-stage)
when	on_success / on_failure / always / manual
allow_failure	Do not fail pipeline
dependencies	Limit which artifacts to fetch
extends	Inherit from a template job

Caching & artifacts

Keyword	Purpose
cache:key / cache:paths	Reusable cache between runs
cache:policy	pull / push / pull-push
artifacts:paths	Files to pass downstream
artifacts:expire_in	Retention window
artifacts:reports	junit, coverage, dotenv

Example

.gitlab-ci.yml

deploy:
  stage: deploy
  extends: .base
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
  needs: [build]
  script: ./deploy.sh ${CI_ENVIRONMENT_NAME}

Key takeaways

Prefer rules over the legacy only/except.
needs creates a DAG so jobs start before their stage.
cache:policy: pull on consumers avoids redundant uploads.

GitLab CI Keywords Cheat Sheet: Every .gitlab-ci.yml Keyword

Job keywords

Control flow

Caching & artifacts

Example

Key takeaways

Related guides