GitLab CI/CD Setup Guide

GitLab CI/CD is built into every GitLab project. You describe your pipeline in a .gitlab-ci.yml file, and GitLab Runner executes the jobs on a machine you control.

Requirements

• A GitLab account (GitLab.com, Self-Managed or Dedicated)
• A project with the code you want to build, test and deploy
• A .gitlab-ci.yml file in the project root
• A GitLab Runner — GitLab.com shared runners, your own runner, or a containerised runner

How a Pipeline Works

Your First Pipeline

Create .gitlab-ci.yml in your project root:

stages:
  - build
  - test
 
default:
  image: node:24
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
 
build:
  stage: build
  script:
    - npm ci
    - npm run build --if-present
  artifacts:
    paths:
      - dist/
    expire_in: 1 week
 
test:
  stage: test
  script:
    - npm ci
    - npm test
  coverage: '/Coverage: \d+\.\d+/'

Push it and open CI/CD → Pipelines to watch the run.

Setting Up Runners

# No tags required — any shared runner can pick the job up
test:
  stage: test
  script:
    - npm test

Common Pipeline Examples

CI/CD Variables

variables:
  STAGING_API: "https://api.staging.example.com"
  PROD_API: "https://api.example.com"
 
deploy_staging:
  script:
    - curl -H "Authorization: Bearer $DEPLOY_TOKEN" "$STAGING_API/deploy"
  environment:
    name: staging

OIDC and ID Tokens

Instead of storing a long-lived cloud key, let GitLab mint a short-lived token:

deploy:
  id_tokens:
    AWS_ID_TOKEN:
      aud: https://gitlab.com
  script:
    - aws configure export-credentials --profile oidc --web-identity-token "$AWS_ID_TOKEN" ...

Cache and Artifacts

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
    - .npm/
 
artifacts:
  paths:
    - dist/
  reports:
    coverage: coverage/lcov.info
    junit: junit.xml
  expire_in: 1 week

• cache speeds up the next job in the same pipeline. It is not uploaded as an artifact and is not visible in the UI.
• artifacts are uploaded, downloadable from the job page, and passed to later stages through needs.

Troubleshooting

Best Practices

1. Version control your pipeline — .gitlab-ci.yml is reviewed like code.
2. Use rules: instead of only: / except:.
3. Pin container images to a digest or an exact tag, never latest.
4. Mask and protect every secret, and prefer OIDC for cloud access.
5. Use needs to parallelise independent jobs and keep the pipeline fast.
6. Set resource_group for jobs that deploy to the same environment, so they cannot run concurrently.
7. Expire artifacts with expire_in so the runner disk does not fill up.
8. Run the Security templates — SAST, dependency scanning and container scanning are a single include away.

Next Steps

• GitLab CI/CD Documentation
• GitLab Runner Documentation
• Pipeline Configuration Reference
• Migrate to the new runner registration workflow
• GitHub Actions Setup Guide
• Jenkins Installation Guide