.gitlab-ci.yml Explained

The .gitlab-ci.yml file is the heart of GitLab CI/CD. It's a YAML file placed at the root of your repository that defines the entire CI/CD pipeline — what jobs to run, when to run them, and how they should execute. Every time you push code to GitLab, the GitLab server reads this file and creates a pipeline based on its contents. This file acts as a blueprint for your continuous integration and continuous delivery process, turning a simple code push into an automated sequence of build, test, and deploy operations.

What makes .gitlab-ci.yml special is that it lives alongside your code in version control. This means your pipeline configuration is versioned, reviewable, and changes go through the same merge request process as your application code. This "configuration as code" approach eliminates the "it works on my machine" problem for pipelines — the exact same pipeline definition runs for everyone, every time, in every environment.

GitLab automatically detects this file in your repository root and executes it. If the file is missing or invalid, no pipeline runs. Understanding its structure and capabilities is essential for getting the most out of GitLab CI/CD. The file is written in YAML, a human-readable data serialization format that uses indentation to define structure — which makes it readable but also means indentation errors are a common source of problems for beginners.

Before diving into GitLab-specific keywords, it's important to understand YAML syntax. YAML (YAML Ain't Markup Language) is a human-readable data format that relies on indentation to define structure. Unlike JSON or XML, YAML uses whitespace and simple punctuation to represent complex data structures, which makes it easy to read but unforgiving of formatting mistakes.

Every YAML file consists of key-value pairs, lists, and nested structures. Keys are separated from values by a colon and a space, list items are denoted by a hyphen and a space, and nesting is achieved through indentation (spaces, never tabs). Understanding these fundamentals is crucial because a single misplaced space or an accidental tab character can cause an entire pipeline to fail before it even starts.

A GitLab CI/CD pipeline consists of stages and jobs organized in a hierarchy. Understanding how these components relate to each other is fundamental to writing effective pipelines. When you push code, GitLab parses your .gitlab-ci.yml file and constructs a pipeline — a directed graph of jobs and stages that will execute in a specific order based on your configuration.

The pipeline structure determines the flow of execution. Stages run sequentially — all jobs in one stage must complete before the next stage begins. Within a stage, jobs run in parallel by default, which means faster feedback but also requires careful thought about shared resources. This two-level hierarchy (stages containing jobs) gives you precise control over the order of operations while maximizing parallelism where it makes sense.

Stages are the top-level organizational unit in a GitLab pipeline. They define the order in which groups of jobs execute. When you define stages, you're creating a sequence — GitLab will run all jobs in the first stage, wait for them all to complete successfully, then move to the next stage, and so on. This sequential execution model is essential for workflows where later steps depend on earlier ones — you can't deploy an application before you've built and tested it.

The power of stages comes from combining sequential stage execution with parallel job execution within each stage. For example, you might have three test jobs in a "test" stage — unit tests, integration tests, and linting — all running simultaneously for faster feedback, while the "deploy" stage only begins after all three tests pass. This balance between order and parallelism is what makes GitLab CI/CD pipelines efficient and reliable.

If you don't explicitly define stages, GitLab uses a default set: .pre, build, test, deploy, and .post. The special .pre and .post stages always run first and last respectively, regardless of where they appear in your stages list.

Jobs are the fundamental building blocks of a GitLab CI/CD pipeline. Each job represents a specific task — compiling code, running tests, building a container image, or deploying to an environment. Every job has a name (the YAML key), a stage it belongs to, and a script that defines what commands to run. Jobs are where the actual work happens; everything else in the .gitlab-ci.yml file is configuration that shapes how and when those jobs execute.

What makes GitLab jobs powerful is their independence. Each job runs in its own isolated environment — by default, a fresh container — meaning one job can't accidentally interfere with another. This isolation guarantees reproducibility: the same job will behave the same way every time it runs, regardless of what other jobs are doing. Jobs in the same stage run in parallel, which means a well-designed pipeline can complete a large amount of work in a fraction of the time it would take to run everything sequentially.

Jobs also have rich configuration options. You can specify which Docker image to use, define environment variables, declare dependencies on other jobs, set timeouts, configure caching, and much more. Understanding these options is key to writing efficient, reliable pipelines.

The script keyword is where all the action happens. It contains the shell commands that a job executes, and it's the only required keyword for any job. Everything else in a job — the image, the variables, the artifacts — exists to support and shape what the script does. When a runner picks up your job, it starts a container, runs your before_script commands, then executes each line of your script sequentially, and finally runs your after_script commands.

Understanding how scripts execute is crucial for writing reliable pipelines. Each line in the script list runs as a separate shell command, but they all share the same shell session within a job. This means environment variables and directory changes persist across lines within a single job, but not across jobs. If any command in the script returns a non-zero exit code, the job fails immediately and subsequent commands don't run. This "fail fast" behavior is what makes pipelines reliable — problems surface at the earliest possible point.

Scripts can be simple one-liners or complex multi-line bash programs. For anything beyond trivial commands, it's often better to put the logic into a script file in your repository and call it from .gitlab-ci.yml. This keeps your pipeline configuration clean and makes the actual logic testable and version-controlled independently.

The rules keyword is the modern way to control when jobs run. It replaced the older only and except keywords and provides much more flexibility. Rules let you define conditions based on branch names, commit messages, file changes, variables, and even the pipeline source. Each rule consists of an if condition and an optional when clause that determines what happens when the condition matches — run the job, run it manually, or skip it entirely.

Rules are evaluated in order, and the first matching rule wins. If no rule matches, the job is not added to the pipeline (equivalent to when: never). This "first match wins" behavior means you should order your rules from most specific to least specific. A common pattern is to have specific rules for different branches or tags first, followed by a catch-all rule at the end that handles everything else.

What makes rules particularly powerful is their ability to inspect the change set. Using changes:, you can run jobs only when specific files are modified — for example, only running frontend tests when frontend code changes. Combined with variables and branch conditions, this enables pipelines that are both efficient and precise, running exactly the work that's needed for each change.

Variables are the mechanism for passing configuration data into your pipeline. They can hold anything from simple strings like branch names to sensitive credentials like API keys and database passwords. GitLab provides three types of variables: predefined variables that GitLab sets automatically (like CI_COMMIT_SHA), custom variables you define in the .gitlab-ci.yml file, and protected/masked variables stored securely in GitLab's settings.

One of the most important things to understand about variables is their scope and priority. Variables defined in the GitLab UI take precedence over variables defined in .gitlab-ci.yml, and job-level variables override pipeline-level ones. This layered approach lets you set sensible defaults in your code while allowing environment-specific overrides from the UI without modifying the pipeline configuration.

Variables are also critical for security. When you store sensitive data as a masked variable in GitLab, its value is hidden in job logs — it appears as [MASKED] even if your script accidentally prints it. Protected variables are even more secure: they're only available on protected branches and tags, which means a compromised feature branch can't exfiltrate production secrets. Together, these features form the foundation of secure CI/CD pipelines.

Artifacts and cache are two related but distinct mechanisms for handling files across jobs and pipelines. Artifacts are files that a job produces and that later jobs need — like a compiled binary, a built container image, or test results. Cache is for files that speed up jobs but aren't strictly necessary — like downloaded dependencies or build caches. Understanding the difference is important because misusing one for the other can lead to subtle bugs and wasted storage.

Artifacts are uploaded to GitLab at the end of a job and downloaded by dependent jobs. They're also available for download from the GitLab UI, which makes them useful for reviewing build outputs and test reports. By default, artifacts are kept for 30 days and are passed to all subsequent jobs, though you can control both behaviors with expire_in and dependencies.

Cache, on the other hand, is stored on the runner (not GitLab) and is reused across pipeline runs. It's perfect for things like node_modules or Maven's .m2 directory — large, unchanging files that take a long time to download. Cache is keyed, typically by branch or by a hash of your lock file, so different branches don't pollute each other's caches. Unlike artifacts, cache may or may not be available (if the runner is new, for example), so your jobs must be able to work with or without it.

Here's a complete, production-ready example that combines all the concepts we've covered. This pipeline demonstrates stages, jobs, scripts, rules, variables, artifacts, and caching in a realistic Node.js application workflow.