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.

Dec 30, 2025 - 18:01
Nov 11, 2026 - 15:43
 0  116
10 GitLab CI Basics Every Fresher Should Know

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 rules to decide when a job runs. The older only and except keywords still work but GitLab recommends rules.
  • 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

#BasicMain keyword or placeWhy it matters
1The pipeline file.gitlab-ci.ymlDefines everything the pipeline does
2Stages and jobsstages, stage, scriptOrder and content of work
3RunnersSettings, tagsWhere jobs execute
4Docker imagesimage, servicesThe tools available to a job
5Variablesvariables, CI/CD settingsConfiguration and secrets
6Rulesrules, whenWhen a job runs
7ArtifactsartifactsPass build output to later stages
8CachecacheFaster dependency installs
9EnvironmentsenvironmentTrack deployments
10DebuggingPipeline editor, job logsFind 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.

ArtifactsCache
PurposePass results between stagesSpeed up repeated work
Typical contentBinaries, reports, build outputDependencies
Guaranteed?Yes, for later jobs in the pipelineNo, best effort
Downloadable from UIYesNo

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:

  1. Syntax. The pipeline editor (Build, Pipeline editor) validates YAML as you type and can show the merged configuration.
  2. Job log. Open the failed job and read from the bottom up. The first error line is usually the real cause.
  3. Why a job did not run. Check its rules and the values of variables such as CI_PIPELINE_SOURCE.
  4. Runner problems. A job stuck in pending usually means no runner with matching tags is online.
  5. Print values. Add echo lines or set the variable CI_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:

  1. Find stages to see the overall order.
  2. Look for default, top-level variables and include; they change every job.
  3. For each job, read stage, image, script and rules. The rules tell you when it actually runs.
  4. Follow artifacts to see which files flow between jobs.
  5. Open the merged view in the pipeline editor if the file uses many includes or extends, so you see the final configuration.
  6. 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

TermMeaning
PipelineOne run of all jobs for a commit, merge request, schedule or manual trigger
JobA named set of commands that runs on a runner
StageA group of jobs that run in parallel; stages run in order
RunnerThe agent that executes jobs
ExecutorHow a runner runs a job: Docker, Shell, Kubernetes and others
ArtifactFiles saved from a job and passed to later jobs or downloaded
CacheFiles reused between pipelines to save time
EnvironmentA deployment target that GitLab tracks, such as staging or production
Merge request pipelineA pipeline that runs for changes in a merge request
Scheduled pipelineA 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.

  1. Create a one-job pipeline that prints $CI_COMMIT_SHORT_SHA and $CI_COMMIT_BRANCH. Push to two branches and compare the logs.
  2. Add three stages with two jobs in the test stage. Watch them run in parallel in the pipeline graph.
  3. Make one test job fail on purpose. Confirm the deploy stage is skipped, then add allow_failure: true and see what changes.
  4. 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.
  5. Add a cache for dependencies and compare job duration on the first and second run.
  6. Add a deploy job with rules so it only runs on the default branch and needs a manual click. Open a merge request and confirm it does not appear there.
  7. Add a masked CI/CD variable in project settings, echo it in a job and check that the log shows [MASKED].
  8. Add an environment to 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 Like 0
Dislike Dislike 0
Love Love 0
Funny Funny 0
Angry Angry 0
Sad Sad 0
Wow Wow 0
Mridul I am a passionate technology enthusiast with a strong focus on DevOps, Cloud Computing, and Cybersecurity. Through my blogs at DevOps Training Institute, I aim to simplify complex concepts and share practical insights for learners and professionals. My goal is to empower readers with knowledge, hands-on tips, and industry best practices to stay ahead in the ever-evolving world of DevOps.