Master GitLab CI/CD: Build, Test, Deploy Efficiently with Real-World Examples

Introduction

GitLab CI/CD is a powerful set of tools provided by GitLab to automate building, testing, and deployment processes, enabling seamless continuous integration and delivery.

Features and Benefits of GitLab CI/CD

GitLab CI/CD automates build, test, and deployment pipelines, ensuring rapid and stable integration of code changes into the main repository and delivery to users. Its main capabilities include:

Automated Build : Builds the code automatically after each commit.

Automated Test : Runs tests immediately after the build to prevent regressions.

Continuous Delivery : Deploys the code to pre‑production or production environments after successful build and test.

Components and Configuration File Format of CI/CD

In GitLab CI/CD, job and pipeline are the two core concepts. Understanding their relationship is essential for effective configuration and management.

Job

A job is the smallest execution unit. Each job defines an independent task such as compilation, testing, or deployment, and can specify scripts, dependencies, and environment variables.

job_name:
  script:
    - echo "This is a job"

Pipeline

A pipeline consists of multiple jobs organized into stages. Stages run sequentially, while jobs within the same stage run in parallel.

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Building the project"

test_job:
  stage: test
  script:
    - echo "Testing the project"

deploy_job:
  stage: deploy
  script:
    - echo "Deploying the project"

Stages

Stages group jobs; jobs in the same stage execute concurrently, and stages execute in order.

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - npm install

unit_test_job:
  stage: test
  script:
    - npm test

deploy_job:
  stage: deploy
  script:
    - npm run deploy

Jobs can share artifacts and define dependencies, allowing one job to use files produced by another. Conditional execution can be configured with only or rules to run jobs on specific branches or tags.

build_job:
  stage: build
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/

test_job:
  stage: test
  script:
    - npm test
  dependencies:
    - build_job

build_job:
  stage: build
  script:
    - npm install
    - npm run build
  only:
    - master

deploy_job:
  stage: deploy
  script:
    - npm run deploy
  only:
    - tags

Local Debugging of GitLab CI/CD

Debug the .gitlab-ci.yml file locally before committing to avoid breaking shared pipelines. Common methods include using Docker with the GitLab Runner image, installing a local Runner, or simulating the pipeline with tools like act.

Docker Local Debugging

docker run -it --rm \
  -v $(pwd):/builds/project_name \
  -w /builds/project_name \
  gitlab/gitlab-runner:latest exec docker job_name

Local GitLab Runner

Install GitLab Runner and execute jobs directly:

[[runners]]
  name = "local-runner"
  url = "https://gitlab.com/"
  token = "your-token"
  executor = "shell"

gitlab-runner exec shell job_name

CI/CD Simulation with act

brew install act
act -j job_name

Example Project: Vue 3 + Egg + TypeScript

A sample .gitlab-ci.yml for a monorepo with separate frontend and backend directories demonstrates stage definitions, environment variables, and deployment steps.

stages:
  - frontend_build
  - backend_build
  - test
  - deploy

frontend_build:
  stage: frontend_build
  script:
    - cd frontend
    - npm install
    - npm run build

backend_build:
  stage: backend_build
  script:
    - cd backend
    - npm install
    - npm run build

test:
  stage: test
  script:
    - cd frontend
    - npm run test
    - cd ../backend
    - npm run test

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

Environment Isolation

Configure different environments (development, staging, production) in the pipeline and set environment‑specific variables to ensure consistent behavior across stages.

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install
    - npm run build
  environment: development

test:
  stage: test
  script:
    - npm run test
  environment: staging

deploy:
  stage: deploy
  script:
    - npm run deploy
  environment: production

Caching Dependencies

Use the cache keyword to share directories like node_modules between jobs, reducing build time.

cache:
  key: my-cache
  paths:
    - node_modules/
    - .cache/
  policy: pull-push

Security

Protect sensitive data such as API keys and database passwords by storing them as GitLab CI/CD secret variables.

Conclusion

GitLab CI/CD is a flexible tool that can greatly improve development efficiency and reliability. By mastering its core components, configuration syntax, debugging methods, and best practices for caching, environment isolation, and security, teams can implement robust continuous integration and delivery pipelines.