GitLab CI/CD:

 

GitLab CI/CD: Complete Guide to Modern DevOps Pipelines

📅 Published: June 2026
⏱️ Estimated Reading Time: 25 minutes
🏷️ Tags: GitLab CI/CD, DevOps, Automation, Pipelines, Continuous Integration

---

Introduction: What is GitLab CI/CD?

GitLab CI/CD is an integrated automation engine built directly into GitLab. Unlike Jenkins or GitHub Actions, which are add-ons to your source control, GitLab CI/CD is a native part of the platform. This tight integration means your pipelines live alongside your code, your security scans run automatically, and your deployments are triggered by the same merge requests you already use for code review.

Why GitLab CI/CD stands out:

• Single application: No separate CI/CD tool to maintain

• Integrated security: SAST, DAST, and container scanning are built-in 

• Merge request pipelines: See test results before you merge

• GitOps ready: Deployments are tracked in Git

• AI assistance: Root cause analysis for failed jobs and vulnerability explanations 

---

Part 1: Core Concepts

The Building Blocks

GitLab CI/CD is built on a hierarchy of concepts that define how your automation runs .

Concept	Description	Example
Pipeline	The complete automation workflow	One pipeline runs per commit or MR
Stage	A logical grouping of jobs	build, test, deploy
Job	A single task within a stage	compile, run-tests, push-to-prod
Runner	The server that executes jobs	GitLab-hosted or self-hosted
Script	The actual commands to run	npm test, go build

How Jobs and Stages Work

Stages run in order. All jobs in a stage must complete before the next stage begins. Jobs within the same stage run in parallel .

yaml

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script: echo "Building the application"

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

deploy-job:
  stage: deploy
  script: echo "Deploying to production"

---

Part 2: Your First .gitlab-ci.yml File

Basic Pipeline Configuration

Create .gitlab-ci.yml in the root of your repository :

yaml

# Define the pipeline stages
stages:
  - build
  - test

# Use a Docker image for all jobs
default:
  image: golang

build-go:
  stage: build
  script:
    - go build

test-go:
  stage: test
  script:
    - go test -v

Understanding the Pipeline

When you commit this file, GitLab creates a pipeline that:

1. Starts a Docker container with the golang image

2. Clones your repository

3. Runs go build in the build stage

4. Runs go test -v in the test stage

Every job runs in its own isolated container, ensuring consistency and preventing interference between jobs .

---

Part 3: Core Pipeline Components

The image Keyword

The image keyword defines which Docker container to use for your job. If you set it at the top level, all jobs use that image. Individual jobs can override this .

yaml

default:
  image: node:18-alpine  # All jobs use Node.js

jobs:
  build:
    script: npm run build

  # Override image for this job
  python-tests:
    image: python:3.9
    script: python -m pytest

Using Artifacts

Artifacts store files from one job so they can be used by later jobs. This is essential for sharing build outputs between stages .

yaml

stages:
  - build
  - test

build-job:
  stage: build
  script:
    - go build -o myapp
  artifacts:
    paths:
      - myapp

test-job:
  stage: test
  script:
    - ./myapp --test

When test-job runs, GitLab automatically downloads the myapp binary from the build-job artifacts .

---

Part 4: Advanced Pipeline Patterns

Parallel Matrix Jobs

Run the same job with different configurations using parallel:matrix .

yaml

test:
  stage: test
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.10", "3.11", "3.12"]
        DB: ["postgres", "mysql"]
  image: python:${PYTHON_VERSION}
  script:
    - pip install -r requirements.txt
    - pytest --db=$DB

This creates six parallel jobs testing three Python versions across two databases.

Parent-Child Pipelines

Split large pipelines into smaller, more manageable pieces. This reduces complexity and improves performance .

yaml

# Parent pipeline
stages:
  - setup
  - test

trigger-child:
  stage: setup
  trigger:
    include: child-pipeline.yml
    strategy: depend

Needs (Skip Stages)

Use needs to skip stages and run jobs as soon as their dependencies are ready. This can dramatically speed up your pipeline .

yaml

build:
  stage: build
  artifacts:
    paths:
      - dist/

test-unit:
  stage: test
  needs: ["build"]  # Runs as soon as build completes
  script: npm test

test-integration:
  stage: test
  needs: ["build"]
  script: npm run test:integration

---

Part 5: Security and Quality

GitLab Auto-DevOps Security Scanning

GitLab can automatically scan your code for vulnerabilities .

yaml

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml
  - template: Security/Container-Scanning.gitlab-ci.yml

Available scanners:

• SAST: Static Application Security Testing

• DAST: Dynamic Application Security Testing

• Secret Detection: Find accidentally committed secrets

• Container Scanning: Scan Docker images for vulnerabilities

• Dependency Scanning: Check dependencies for known issues

Merge Trains

Keep your main branch green even with multiple developers merging simultaneously .

yaml

merge_trains:
  enabled: true

When merge trains are enabled, GitLab automatically creates a pipeline for each merge request that includes all changes ahead of it in the train. If the pipeline passes, the merge happens automatically.

---

Part 6: Deployment Pipelines

Environments and Deployments

yaml

stages:
  - test
  - deploy-staging
  - deploy-prod

deploy-staging:
  stage: deploy-staging
  script: ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com

deploy-prod:
  stage: deploy-prod
  script: ./deploy.sh production
  environment:
    name: production
    url: https://example.com
  when: manual  # Manual approval for production
  only:
    - main

Progressive Deployments

GitLab supports canary deployments for risk-free rollouts .

yaml

deploy-canary:
  stage: deploy-canary
  script: ./deploy-canary.sh
  environment:
    name: production
    deployment_tier: production
  strategy: canary

---

Part 7: Multi-Project Pipelines

Trigger pipelines in other projects automatically .

yaml

test:
  stage: test
  script: npm test

deploy-downstream:
  stage: deploy
  trigger:
    project: my-org/infrastructure
    branch: main

This is useful for monorepo setups or when your application deployment triggers infrastructure updates.

---

Part 8: CI/CD Components (Catalog)

GitLab CI/CD Components are reusable pipeline building blocks .

Using a Component

yaml

include:
  - component: gitlab.com/org/my-component@v1.0.0
    inputs:
      node_version: "18"
      environment: "production"

Creating a Component

Create a component directory with a template file:

text

components/my-component/
├── template.yml
└── README.md

template.yml:

yaml

spec:
  inputs:
    node_version:
      default: "16"
    environment:
      default: "development"

---
# Component content
test:
  script:
    - echo "Testing with Node ${{ inputs.node_version }} on ${{ inputs.environment }}"

---

GitLab CI/CD Commands Cheat Sheet

bash

# Run pipeline manually
curl -X POST \
  -H "PRIVATE-TOKEN: your_token" \
  "https://gitlab.com/api/v4/projects/1/trigger/pipeline"

# Trigger pipeline from another project
curl -X POST \
  -F "token=TRIGGER_TOKEN" \
  -F "ref=main" \
  "https://gitlab.com/api/v4/projects/1/trigger/pipeline"

# List pipelines
curl -H "PRIVATE-TOKEN: your_token" \
  "https://gitlab.com/api/v4/projects/1/pipelines"

---

GitLab CI/CD Best Practices

Pipeline Design

• Use small, focused jobs – Easier to debug and faster to run

• Cache dependencies – Speed up subsequent runs

• Use artifacts for build outputs – Share data between jobs

• Run tests in parallel – Use parallel:matrix for efficiency

• Add manual approvals for production – Prevent accidental deployments

Security

• Never store secrets in .gitlab-ci.yml – Use CI/CD variables

• Enable Auto-DevOps security scanning – Catch vulnerabilities early

• Use protected branches – Restrict who can deploy to production

• Scan containers – Check for vulnerabilities before deployment

Performance

• Use needs to skip unnecessary stages – Speed up pipelines 

• Use merge trains – Keep main branch green with CI/CD 

• Use GitLab-hosted runners – Reduce infrastructure overhead

• Use smaller Docker images – Faster pull times (Alpine instead of full OS)

---

GitLab CI/CD vs Other Tools

Feature	GitLab CI/CD	GitHub Actions	Jenkins
Integration	Native	Native	Plugin-based
Security scanning	Built-in	Marketplace	Plugin-based
Learning curve	Moderate	Moderate	Steep
Self-hosted	✅	✅	✅
Merge trains	✅	❌	❌
Multi-project pipelines	✅	❌	Plugin
Parent-child pipelines	✅	❌	❌

---

Summary

GitLab CI/CD provides a complete, integrated automation platform that grows with your team. Start with a simple .gitlab-ci.yml file. Add security scanning as you grow. Add deployment pipelines when you're ready.

Stage	What to Automate	GitLab Feature
Code	Build, lint, unit tests	Basic pipeline
Security	SAST, DAST, secret detection	Auto-DevOps templates
Deploy	Staging, production deployments	Environments, manual approvals
Scale	Merge trains, parallel jobs	Advanced pipeline patterns

---

Learn More

Practice GitLab CI/CD with hands-on exercises in our interactive labs:
https://devops.trainwithsky.com