GitLab CI/CD Tutorial: .gitlab-ci.yml, Runners, Artifacts, Environments and Auto DevOps Ideas
GitLab CI/CD Overview
GitLab includes CI/CD in the same product as Git hosting, issues and the container registry. You define the pipeline in a .gitlab-ci.yml file at the repository root. Runners (agents) pick up jobs and execute them.
| Term | Meaning |
|---|---|
| Pipeline | One complete run for a commit |
| Stage | A group of jobs. Stages run in order, jobs inside a stage run in parallel |
| Job | A unit of work with a script |
| Runner | Machine or container that runs jobs (shared, group or project runners) |
| Executor | How a runner runs jobs: shell, Docker, Kubernetes |
| Artifacts | Files passed between jobs or downloaded after |
| Environment | A named deployment target such as staging or production |
First Pipeline
yaml
# .gitlab-ci.yml
stages:
- build
- test
- deploy
default:
image: node:22-alpine
build:
stage: build
script:
- npm ci
- npm run build
artifacts:
paths: [dist/]
expire_in: 1 week
cache:
key:
files: [package-lock.json]
paths: [.npm/]
unit-test:
stage: test
script:
- npm ci --cache .npm
- npm test
coverage: '/All files\s*\|\s*([\d.]+)/'
lint:
stage: test
script:
- npm run lint
deploy-staging:
stage: deploy
script:
- echo "Deploying to staging"
environment:
name: staging
url: https://staging.example.com
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Runners
bash
# Register a Docker-executor runner on a server (token from Settings > CI/CD > Runners)
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt install gitlab-runner
sudo gitlab-runner register --url https://gitlab.example.com --token glrt-XXXX --executor docker --docker-image alpine:3.20
Version note: GitLab introduced runner authentication tokens that replace the old registration tokens. Follow the current GitLab documentation for your GitLab version.
Variables and Secrets
- Set in Settings, CI/CD, Variables. Mark as Masked (hidden in logs) and Protected (only on protected branches and tags)
- Predefined variables:
$CI_COMMIT_SHA,$CI_COMMIT_SHORT_SHA,$CI_COMMIT_BRANCH,$CI_PIPELINE_ID,$CI_PROJECT_NAME,$CI_REGISTRY_IMAGE,$CI_DEFAULT_BRANCH - Use File type variables for kubeconfig
- Prefer **OIDC (
id_tokens)** with HashiCorp Vault or cloud IAM over static keys
Rules: When Does a Job Run?
yaml
job:
script: echo hi
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_TAG =~ /^v\d+/
when: manual # needs a click
- changes: [docs/**]
when: never
Build and Push a Docker Image to GitLab Registry
yaml
build-image:
stage: build
image: docker:27
services:
- docker:27-dind
variables:
DOCKER_TLS_CERTDIR: "/certs"
before_script:
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
script:
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Without privileged Docker-in-Docker: Use Kaniko, Buildah or BuildKit rootless to build images inside Kubernetes runners without privileged mode.
Deploy to Kubernetes
yaml
deploy-prod:
stage: deploy
image:
name: bitnami/kubectl:latest
entrypoint: [""]
script:
- kubectl --kubeconfig "$KUBECONFIG_PROD" set image deployment/shop-api api="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" -n prod
- kubectl --kubeconfig "$KUBECONFIG_PROD" rollout status deployment/shop-api -n prod --timeout=180s
environment:
name: production
url: https://shop.example.com
when: manual
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Review Apps (Per Merge Request Environments)
yaml
review:
stage: deploy
script:
- helm upgrade --install review-$CI_MERGE_REQUEST_IID ./chart --set ingress.host=mr-$CI_MERGE_REQUEST_IID.example.com
environment:
name: review/$CI_MERGE_REQUEST_IID
url: https://mr-$CI_MERGE_REQUEST_IID.example.com
on_stop: stop-review
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
stop-review:
stage: deploy
script: helm uninstall review-$CI_MERGE_REQUEST_IID
environment: { name: review/$CI_MERGE_REQUEST_IID, action: stop }
when: manual
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
Reuse: include, extends and Templates
yaml
include:
- template: Security/SAST.gitlab-ci.yml # GitLab-provided security templates
- template: Security/Secret-Detection.gitlab-ci.yml
- project: platform/ci-templates
ref: main
file: /templates/deploy.yml
.deploy-base: # hidden job (starts with a dot) used as a template
image: bitnami/kubectl
before_script: [echo "setup"]
deploy-dev:
extends: .deploy-base
script: ["echo deploy dev"]
Other Useful Features
needs:creates a DAG so jobs start as soon as their dependencies finish, without waiting for the whole stageparallel: matrix:runs a job with several variable combinations- Child pipelines and multi-project pipelines for monorepos
- Merge request pipelines run tests on the merged result
retry:andtimeout:for flaky or long jobs- Pipeline schedules for nightly builds, and protected environments for approvals
Practice Tasks
- Create a pipeline with build, test and deploy stages for a small app
- Add cache and artifacts, and check how much time caching saves
- Build and push an image to the GitLab registry, tagged with the short SHA
- Add a manual production deployment with a protected environment
- Include the SAST and Secret Detection templates and read the report
Conclusion
GitLab CI/CD uses a single .gitlab-ci.yml, stages and jobs, runners, rules, caches, artifacts and environments. With the built-in registry and templates it gives a complete delivery platform.
Quick Summary: .gitlab-ci.yml stages/jobs; runners; masked+protected vars; rules; cache/artifacts; environments; include/extends.

