GitLab CI reference

GitLab CI configuration lives in a single `.gitlab-ci.yml` at the repo root. Top-level keys cover global behaviour (`stages`, `variables`, `cache`, `default`, `workflow`, `include`); every other top-level key is a job. Each job has a `stage:`, a `script:` (the actual commands), and optional `rules:`, `needs:`, `cache:`, `artifacts:`, and `services:`.

Expression syntax uses `$CI_*` predefined variables and shell-style `$VAR` interpolation. Conditions in `rules.if` use a small DSL with `==`, `!=`, `||`, `&&`, and regex matchers `=~`.

Top-level keys

Key	Purpose
stages	Ordered list of stages; jobs run stage-by-stage.
variables	Pipeline-level environment variables.
image	Default Docker image for jobs.
services	Default sidecar containers (database, etc.).
default	Default values for image, before_script, after_script, cache, tags, retry, etc.
workflow	Pipeline-level rules deciding whether the pipeline runs.
include	Pull other YAML files (local, remote, project-level, template).
cache	Job-level (or global) cache definition.
<job>.script	List of shell commands to run in the job.
<job>.before_script / after_script	Lines that run before / after the main script.
<job>.rules	When the job runs (replaces the older only/except).
<job>.parallel	Numeric or matrix parallelism.
<job>.needs	DAG-style cross-stage dependencies.
<job>.artifacts	Paths to upload + retention.

Minimal example

stages: [test]

test:
  stage: test
  image: node:20
  cache:
    paths: [node_modules/]
  script:
    - npm ci
    - npm test

Context variables

The same concept goes by a different name on every platform. Use this table when porting expressions and conditions.

Concept	GitHub Actions	GitLab CI	CircleCI	Bitbucket
Branch name	github.ref_name	$CI_COMMIT_REF_NAME	<< pipeline.git.branch >>	$BITBUCKET_BRANCH
Commit SHA	github.sha	$CI_COMMIT_SHA	<< pipeline.git.revision >>	$BITBUCKET_COMMIT
Tag name	github.ref_name	$CI_COMMIT_TAG	<< pipeline.git.tag >>	$BITBUCKET_TAG
Repository slug	github.repository	$CI_PROJECT_PATH	<< pipeline.project.git_url >>	$BITBUCKET_REPO_FULL_NAME
Run / pipeline id	github.run_id	$CI_PIPELINE_ID	<< pipeline.id >>	$BITBUCKET_BUILD_NUMBER
Triggering event	github.event_name	$CI_PIPELINE_SOURCE	<< pipeline.trigger_source >>	(implicit; check pipelines.* section)
Actor / user	github.actor	$GITLAB_USER_LOGIN	$CIRCLE_USERNAME	$BITBUCKET_STEP_TRIGGERER_UUID
Workspace path	github.workspace	$CI_PROJECT_DIR	$CIRCLE_WORKING_DIRECTORY	$BITBUCKET_CLONE_DIR
PR / MR source branch	github.head_ref	$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	$CIRCLE_BRANCH (head ref)	$BITBUCKET_PR_DESTINATION_BRANCH (target only)
PR / MR target branch	github.base_ref	$CI_MERGE_REQUEST_TARGET_BRANCH_NAME	(not directly exposed)	$BITBUCKET_PR_DESTINATION_BRANCH

Related Tools

data_object

YAML Formatter

Format and validate YAML. Convert YAML to JSON or JSON to YAML. Supports 2 and 4 space indentation.

timer

Cron Builder

Visual builder for cron-job schedules.

filter_list_off

Gitignore Generator

Generate .gitignore files for any language, framework, or IDE — 100+ templates, 100% client-side.

schema

JSON Schema Generator

Generate a JSON Schema from one or more sample JSONs — drafts 2020-12, 2019-09, 7, 6, 4. Detects formats (date-time, email, uuid, ipv4, uri), extracts $defs, validates with AJV, and exports to YAML, TypeScript, and Zod. 100% in your browser.

auto_awesome

AI Coding Rules

Curated rules-file library and generator for Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Aider, Continue, and Cody. Browse 20 hand-crafted .cursorrules / CLAUDE.md / copilot-instructions.md files for popular stacks, build a custom one with the wizard, or convert any rules file between AI-tool formats.