GitLab CI/CD: Setup, Usage, and Best Practices

Introduction

In modern software development, Continuous Integration (CI) and Continuous Delivery/Deployment (CD) are core pillars of the DevOps culture.
GitLab integrates CI/CD features directly, offering developers a powerful, flexible, and scalable solution.

In this article, you’ll learn:

• The fundamentals of GitLab CI/CD,
• The structure of .gitlab-ci.yml,
• How to install GitLab Runner,
• Realistic pipeline examples,
• Docker and Kubernetes integration,
• Best practices for production-ready pipelines.

Prerequisites

Before starting, make sure you have:

• A GitLab account (self-hosted or gitlab.com),
• Basic Git knowledge,
• A system with Docker installed,
• A simple project (e.g., Python Flask, Node.js Express).

Step 1 – GitLab CI/CD Basics

1.1 What is CI/CD?

• CI (Continuous Integration): Developers frequently integrate code into the main branch, with automated tests validating changes.
• CD (Continuous Delivery/Deployment): Automates delivery of code to staging or production.

1.2 How GitLab CI/CD Works

• Pipelines are defined as stages and jobs.
• The configuration lives in .gitlab-ci.yml.
• Example pipeline: build → test → deploy.

stages:
  - build
  - test
  - deploy

1.3 GitLab Runner

• A Runner executes jobs.
• Can be installed locally, on servers, or in Kubernetes.

Step 2 – Writing Your First Pipeline

2.1 Minimal .gitlab-ci.yml

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script:
    - echo "Building the app..."

test-job:
  stage: test
  script:
    - echo "Running tests..."

deploy-job:
  stage: deploy
  script:
    - echo "Deploying..."

2.2 Jobs and Stages

• Stages: Pipeline phases (build, test, deploy).
• Jobs: Tasks executed in each stage.
• Script: Commands that define job behavior.

2.3 Artifacts and Cache

build-job:
  stage: build
  script:
    - mkdir dist
    - echo "Build output" > dist/output.txt
  artifacts:
    paths:
      - dist/

Step 3 – Installing GitLab Runner

3.1 Install on Linux

sudo apt-get install -y curl
curl -L --output gitlab-runner.deb https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb
sudo dpkg -i gitlab-runner.deb

3.2 Register Runner

sudo gitlab-runner register

Information required:

• GitLab URL: https://gitlab.com/
• Token: Found in project settings
• Executor: Recommended docker

3.3 Docker Executor

[[runners]]
  name = "docker-runner"
  executor = "docker"
  [runners.docker]
    image = "python:3.10"
    privileged = true

Step 4 – Using Docker in Pipelines

4.1 Docker-in-Docker

image: docker:latest

services:
  - docker:dind

stages:
  - build

build-job:
  stage: build
  script:
    - docker build -t myapp .

4.2 Node.js Example

image: node:18

stages:
  - install
  - test

install-job:
  stage: install
  script:
    - npm install

test-job:
  stage: test
  script:
    - npm test

4.3 Python Flask Example

image: python:3.10

stages:
  - test

test-job:
  stage: test
  script:
    - pip install -r requirements.txt
    - pytest

Step 5 – Environments and Deployment Strategies

5.1 Staging Environment

deploy-staging:
  stage: deploy
  script:
    - echo "Deploying to staging..."
  environment:
    name: staging
    url: https://staging.example.com

5.2 Manual Approval for Production

deploy-production:
  stage: deploy
  script:
    - echo "Deploying to production..."
  when: manual
  environment:
    name: production
    url: https://example.com

5.3 Blue-Green and Canary

• Blue-Green: Two parallel environments, one live, one idle.
• Canary: Roll out to a small portion of users first.

Step 6 – Best Practices

• Caching: Save dependencies for faster pipelines.
• Artifacts: Pass build results between jobs.
• Secrets Management: Use GitLab CI/CD variables.
• Parallel Jobs: Run tests simultaneously.
• Monitoring: Track pipeline metrics with Prometheus/Grafana.

Step 7 – Kubernetes Integration

7.1 Deploy to Kubernetes

deploy-k8s:
  stage: deploy
  image: bitnami/kubectl
  script:
    - kubectl apply -f k8s/deployment.yaml
  environment:
    name: production
    url: https://k8s.example.com

7.2 Helm Deployment

deploy-helm:
  stage: deploy
  script:
    - helm upgrade --install myapp ./chart

Conclusion

In this article, you learned the basics of GitLab CI/CD:

• .gitlab-ci.yml structure,
• Runner installation,
• Docker and Kubernetes integration,
• Environment and deployment strategies,
• Best practices.