Introduction
In GitLab CI/CD, thestages keyword defines the sequence in which jobs execute. Without an explicit order, all jobs run in parallel—leading to situations where tests or deployments start before your build finishes and ultimately fail. By declaring an ordered list of stages and assigning each job to one, you ensure a reliable, sequential pipeline: build → test → deploy.
All GitLab CI/CD YAML syntax is covered in the official GitLab docs.
Defining Stages in Your .gitlab-ci.yml
1. Basic stages Syntax
stages represents a phase of your pipeline. Jobs in the same stage run in parallel, while stages themselves execute one after another.
2. Assigning Jobs to Stages
compile_code runs first. If it succeeds, run_tests starts. Finally, deploy_app executes only after tests pass.
Example: Full Pipeline Configuration
Below is a complete pipeline that installs a gem, generates ASCII art in a file, then tests and deploys based on that file.- workflow.name: Gives your pipeline a friendly title.
- build_job: Installs
cowsay, waits 30s, and writes ASCII art todragon.txt. - test_job: Waits 10s then searches for “dragon” inside
dragon.txt. - deploy_job: Runs only if the test stage succeeds.
Jobs must be assigned to one of the listed
stages. Assigning a job to an undefined stage will trigger a pipeline editor warning.Exploring Pipeline Visualization
Once committed, GitLab runs the pipeline in three sequential stages. Use the Visualize tab in the pipeline editor to confirm the flow before pushing changes.
Analyzing Job Output
Build Job Logs
Test Job Failure
Because each job runs in its own runner environment, artifacts created in
build aren’t available in test by default. You must configure artifacts to pass files between stages.Passing Data with Artifacts
To preserve files likedragon.txt across stages, add an artifacts section to your build job: