GitLab CI/CD Tutorial: .gitlab-ci.yml, Runners, Artifacts, Environments and Auto DevOps Ideas

DevOps Certification 20 min min read Updated: Nov 17, 2026 Intermediate
GitLab CI/CD Tutorial: .gitlab-ci.yml, Runners, Artifacts, Environments and Auto DevOps Ideas
Intermediate Topic 4 of 4

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.

TermMeaning
PipelineOne complete run for a commit
StageA group of jobs. Stages run in order, jobs inside a stage run in parallel
JobA unit of work with a script
RunnerMachine or container that runs jobs (shared, group or project runners)
ExecutorHow a runner runs jobs: shell, Docker, Kubernetes
ArtifactsFiles passed between jobs or downloaded after
EnvironmentA 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 stage
  • parallel: 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: and timeout: for flaky or long jobs
  • Pipeline schedules for nightly builds, and protected environments for approvals

Practice Tasks

  1. Create a pipeline with build, test and deploy stages for a small app
  2. Add cache and artifacts, and check how much time caching saves
  3. Build and push an image to the GitLab registry, tagged with the short SHA
  4. Add a manual production deployment with a protected environment
  5. 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.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators