gitlab-ci

When to use this skill

Use this skill whenever the user wants to:

• Write or debug GitLab CI pipelines (.gitlab-ci.yml)
• Configure GitLab Runner, stages, jobs, and artifacts
• Set up CI/CD variables, secrets, and environments
• Integrate testing, building, and deployment automation
• Use needs for complex dependency graphs between jobs

How to use this skill

Workflow

1. Define stages — declare the pipeline execution order
2. Write jobs — assign each job to a stage with scripts and rules
3. Configure artifacts and cache — pass build outputs between jobs
4. Set up environments — define deployment targets with rules

Quick Start Example

# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  NODE_VERSION: "20"

test:
  stage: test
  image: node:${NODE_VERSION}
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  script:
    - npm ci
    - npm test
  artifacts:
    when: on_failure
    paths:
      - test-reports/
    expire_in: 7 days

build:
  stage: build
  image: node:${NODE_VERSION}
  needs: [test]
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

deploy_production:
  stage: deploy
  needs: [build]
  environment:
    name: production
    url: https://myapp.example.com
  script:
    - ./scripts/deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Key Concepts

Feature	Purpose
stages	Define execution order
needs	Create DAG dependencies (skip stage waiting)
artifacts	Pass files between jobs
cache	Speed up repeated installs
rules	Control when jobs run
environment	Track deployment targets

Best Practices

• Use stages to define clear build order; jobs within a stage run in parallel
• Store sensitive values in CI/CD Variables (Settings > CI/CD > Variables) — never hardcode in YAML
• Use needs to create complex dependency graphs and avoid unnecessary waiting
• Preserve logs and artifacts on failure with artifacts: when: on_failure
• Use rules instead of deprecated only/except for conditional job execution

Troubleshooting

• Job stuck pending: Check runner tags match and runners are available
• Artifact not found: Verify the producing job completed and artifact paths are correct
• Cache not restoring: Ensure cache key is consistent; check runner cache configuration
• Pipeline not triggered: Verify rules conditions match the event (push, merge request, etc.)

Keywords

gitlab ci, gitlab-ci, pipeline, runner, ci/cd, artifacts, cache, environments, deployment automation