10 GitLab CI Basics Every Fresher Should Know
Learn 10 GitLab CI basics for freshers: .gitlab-ci.yml, stages, jobs, runners, images, variables, rules, artifacts, cache and environments.
GitLab CI runs automated jobs defined in a file called .gitlab-ci.yml at the root of your repository. Freshers need ten basics to read and write pipelines: the file itself, stages and jobs, runners, images, variables, rules, artifacts, cache, environments and debugging with the pipeline editor. Learn these before moving on to advanced features.
This guide is for beginners. Once these basics feel natural, continue with our advanced post 10 GitLab CI/CD secrets used by DevOps experts, which covers DAG pipelines, CI/CD components, OIDC and parent-child pipelines. For a broader view of the product, see top GitLab features to explore.
Key takeaways
- A pipeline is made of jobs grouped into stages. Jobs in the same stage run in parallel; stages run in order.
- Jobs run on runners. On GitLab.com, GitLab provides hosted runners; you can also register your own.
- Use
rulesto decide when a job runs. The olderonlyandexceptkeywords still work but GitLab recommendsrules. - Artifacts pass files between stages; cache speeds up repeated downloads. They solve different problems.
- Never write passwords or tokens in .gitlab-ci.yml. Store them as masked CI/CD variables.
The 10 basics at a glance
| # | Basic | Main keyword or place | Why it matters |
|---|---|---|---|
| 1 | The pipeline file | .gitlab-ci.yml | Defines everything the pipeline does |
| 2 | Stages and jobs | stages, stage, script | Order and content of work |
| 3 | Runners | Settings, tags | Where jobs execute |
| 4 | Docker images | image, services | The tools available to a job |
| 5 | Variables | variables, CI/CD settings | Configuration and secrets |
| 6 | Rules | rules, when | When a job runs |
| 7 | Artifacts | artifacts | Pass build output to later stages |
| 8 | Cache | cache | Faster dependency installs |
| 9 | Environments | environment | Track deployments |
| 10 | Debugging | Pipeline editor, job logs | Find and fix failures |
1. The .gitlab-ci.yml file
GitLab looks for a file named .gitlab-ci.yml in the root of the repository. When you push a commit, GitLab reads it and creates a pipeline. The file is YAML, so indentation with spaces matters and tabs cause errors. The full keyword list is in the CI/CD YAML syntax reference.
The smallest useful pipeline has one job:
hello:
script:
- echo "Hello from GitLab CI"
A job with no stage goes into the default test stage.
2. Stages and jobs
A job is a named set of commands under script. Stages group jobs and set the order. By default the stages are .pre, build, test, deploy and .post; you can define your own list.
stages:
- build
- test
- deploy
build_app:
stage: build
script:
- echo "Compiling..."
unit_tests:
stage: test
script:
- echo "Running unit tests..."
lint:
stage: test
script:
- echo "Running linter..."
deploy_app:
stage: deploy
script:
- echo "Deploying..."
Here unit_tests and lint run at the same time, after build_app succeeds. If any job in a stage fails, later stages do not run unless you change that with allow_failure or when. Other job-level keywords you will meet early are before_script and after_script, which run commands before and after the main script.
3. Runners
A runner is the agent that picks up jobs and runs them. GitLab Runner is a separate program you can install on a VM, a container or Kubernetes. On GitLab.com, GitLab-hosted runners are available to projects (GitLab now calls the shared ones "instance runners"; older guides say "shared runners"). You can also register project runners or group runners for your own machines.
Runners use an executor, most commonly Docker, Shell or Kubernetes. Use tags to send a job to a runner with matching tags:
build_on_own_runner:
tags:
- linux
- docker
script:
- make build
Read about runner types in the GitLab Runner documentation. Once you run your own, our GitLab Runner optimisation tips help keep them fast.
4. Docker images and services
With the Docker executor, each job runs inside a container. The image keyword picks it, so the job has the right tools. services starts extra containers, such as a database for integration tests, reachable by hostname.
test_python:
image: python:3.12
services:
- postgres:16
variables:
POSTGRES_DB: app_test
POSTGRES_USER: runner
POSTGRES_PASSWORD: example-only
script:
- pip install -r requirements.txt
- pytest
The password above is a throwaway value for a test container that exists only during the job. Pin image versions (python:3.12, not python:latest) so pipelines do not break when a new release appears.
5. Variables
Variables hold configuration. You can set them in the YAML file, in project or group settings under CI/CD variables, or use the predefined ones GitLab provides, such as CI_COMMIT_SHA, CI_COMMIT_BRANCH, CI_DEFAULT_BRANCH, CI_PIPELINE_SOURCE and CI_REGISTRY_IMAGE. The full list is in predefined CI/CD variables.
variables:
APP_NAME: "shop-api"
print_info:
script:
- echo "Building $APP_NAME at commit $CI_COMMIT_SHORT_SHA"
For secrets such as API tokens, add them in Settings, CI/CD, Variables and mark them masked (hidden in job logs) and protected (only available on protected branches and tags). Masking hides the value in logs but does not stop a job script from sending it elsewhere, so limit who can edit pipelines. Our post on storing secrets safely in Git explains why secrets never belong in the repository.
6. Rules: deciding when a job runs
rules is a list of conditions checked in order; the first match decides whether the job runs and how. It replaced only and except, which GitLab still supports but no longer develops.
deploy_staging:
stage: deploy
script:
- ./deploy.sh staging
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
review_check:
script:
- echo "Runs only in merge request pipelines"
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
You can also use changes to run a job only when certain files change, and when: manual to require a button press. See rules documentation for all options.
7. Artifacts
Each job starts in a fresh environment, so files created in one job are not automatically available in the next. Artifacts solve that: the runner uploads the listed paths to GitLab, and jobs in later stages download them.
build_app:
stage: build
script:
- mkdir -p dist
- echo "binary" > dist/app
artifacts:
paths:
- dist/
expire_in: 1 week
test_app:
stage: test
script:
- ls dist/
Artifacts can also be test reports (artifacts:reports:junit) that GitLab shows in merge requests.
8. Cache
Cache stores files that are slow to download, such as node_modules or pip packages, so the next pipeline can reuse them. Unlike artifacts, cache is a speed optimisation: a job must still work if the cache is empty.
install_deps:
image: node:20
cache:
key:
files:
- package-lock.json
paths:
- node_modules/
script:
- npm ci
Using the lock file as the cache key gives a new cache whenever dependencies change.
| Artifacts | Cache | |
|---|---|---|
| Purpose | Pass results between stages | Speed up repeated work |
| Typical content | Binaries, reports, build output | Dependencies |
| Guaranteed? | Yes, for later jobs in the pipeline | No, best effort |
| Downloadable from UI | Yes | No |
9. Environments
The environment keyword tells GitLab that a job deploys somewhere. GitLab then records each deployment, shows which commit is live in each environment and lets you roll back by re-running an earlier deployment job.
deploy_production:
stage: deploy
script:
- ./deploy.sh production
environment:
name: production
url: https://www.example.com
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
Protected environments can restrict who may deploy to production.
10. Debugging pipelines
When a pipeline fails, check in this order:
- Syntax. The pipeline editor (Build, Pipeline editor) validates YAML as you type and can show the merged configuration.
- Job log. Open the failed job and read from the bottom up. The first error line is usually the real cause.
- Why a job did not run. Check its
rulesand the values of variables such asCI_PIPELINE_SOURCE. - Runner problems. A job stuck in pending usually means no runner with matching tags is online.
- Print values. Add
echolines or set the variableCI_DEBUG_TRACE: "true"for very detailed output. Debug trace can expose secret values in the log, so use it only briefly and never on public projects.
Two more keywords worth knowing early: default and include
default sets values that apply to every job unless a job overrides them, such as image, before_script or tags. It removes repetition from small pipelines.
include pulls YAML from other files into your pipeline. It can load a local file in the same repo, a file from another project, a remote URL or a GitLab-maintained template. Templates are how many teams add features like SAST scanning with one line:
include:
- local: ci/build.yml
- template: Jobs/SAST.gitlab-ci.yml
Check the template name against the include documentation and the security scanning docs for your GitLab version, because template paths change over time. Reusable CI/CD components, which are the newer way to share pipeline code, are covered in the advanced post linked at the top.
How to read a pipeline someone else wrote
As a fresher you will read far more pipelines than you write. A simple method:
- Find
stagesto see the overall order. - Look for
default, top-levelvariablesandinclude; they change every job. - For each job, read
stage,image,scriptandrules. The rules tell you when it actually runs. - Follow
artifactsto see which files flow between jobs. - Open the merged view in the pipeline editor if the file uses many includes or
extends, so you see the final configuration. - Compare with a real pipeline run in the Pipelines page; the graph shows which jobs ran and which were skipped.
Glossary for GitLab CI beginners
| Term | Meaning |
|---|---|
| Pipeline | One run of all jobs for a commit, merge request, schedule or manual trigger |
| Job | A named set of commands that runs on a runner |
| Stage | A group of jobs that run in parallel; stages run in order |
| Runner | The agent that executes jobs |
| Executor | How a runner runs a job: Docker, Shell, Kubernetes and others |
| Artifact | Files saved from a job and passed to later jobs or downloaded |
| Cache | Files reused between pipelines to save time |
| Environment | A deployment target that GitLab tracks, such as staging or production |
| Merge request pipeline | A pipeline that runs for changes in a merge request |
| Scheduled pipeline | A pipeline triggered on a cron-style schedule set in the project |
A complete beginner pipeline
stages:
- build
- test
- deploy
default:
image: node:20
variables:
APP_NAME: "demo-app"
install_and_build:
stage: build
cache:
key:
files:
- package-lock.json
paths:
- node_modules/
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/
unit_tests:
stage: test
script:
- npm ci
- npm test
deploy_staging:
stage: deploy
script:
- echo "Deploying $APP_NAME to staging"
environment:
name: staging
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Our post with 15 GitLab CI/CD pipeline examples builds on this with Docker, Terraform and Kubernetes deployments. When you are ready for interviews, try GitLab CI/CD interview questions for freshers. For guided labs, see our GitLab training in Kharadi, Pune and live online.
Practice exercises
Work through these in a free GitLab.com project. Each one builds on the last.
- Create a one-job pipeline that prints
$CI_COMMIT_SHORT_SHAand$CI_COMMIT_BRANCH. Push to two branches and compare the logs. - Add three stages with two jobs in the test stage. Watch them run in parallel in the pipeline graph.
- Make one test job fail on purpose. Confirm the deploy stage is skipped, then add
allow_failure: trueand see what changes. - Write a file in the build job, save it as an artifact and read it in a test job. Remove the artifact block and observe the failure.
- Add a cache for dependencies and compare job duration on the first and second run.
- Add a deploy job with
rulesso it only runs on the default branch and needs a manual click. Open a merge request and confirm it does not appear there. - Add a masked CI/CD variable in project settings, echo it in a job and check that the log shows
[MASKED]. - Add an
environmentto the deploy job and look at the Operate, Environments page after it runs.
Breaking things on purpose, as in exercises 3 and 4, teaches you how GitLab behaves faster than reading about it. Keep the project; it is a good base for the examples in our advanced post.
Frequently asked questions
What is .gitlab-ci.yml?
The YAML file at the root of a repository that defines a GitLab CI/CD pipeline: its stages, jobs, scripts and rules. GitLab reads it on every push.
What is the difference between a stage and a job?
A job is a set of commands that runs on a runner. A stage groups jobs; jobs in one stage run in parallel and stages run in order.
What is a GitLab runner?
The agent that executes jobs. GitLab.com provides hosted runners, and you can install GitLab Runner on your own machines or Kubernetes.
What is the difference between artifacts and cache?
Artifacts pass job output to later stages and can be downloaded. Cache stores dependencies to speed up future jobs and is not guaranteed to exist.
Should I use rules or only/except?
Use rules. GitLab recommends rules for new pipelines because they are more flexible; only and except are no longer actively developed.
How do I store passwords in GitLab CI?
Add them as CI/CD variables in project or group settings, marked masked and protected. Never put them in .gitlab-ci.yml.
Why is my GitLab job stuck in pending?
Usually no available runner matches the job's tags, or runners are disabled for the project. Check the runner settings and job tags.
References
What's Your Reaction?
Like
0
Dislike
0
Love
0
Funny
0
Angry
0
Sad
0
Wow
0