Gitlab Ci

---
name: gitlab-ci
description: "Covers GitLab CI/CD: .gitlab-ci.yml, pipelines, stages, jobs, runners, artifacts, caching, environments, CI/CD components, Auto DevOps, and GitLab DevSecOps integration. WHEN: \"GitLab CI\", \".gitlab-ci.yml\", \"GitLab pipeline\", \"GitLab runner\", \"GitLab stages\", \"GitLab artifacts\", \"GitLab environments\", \"GitLab CI/CD components\", \"Auto DevOps\", \"GitLab SAST\", \"GitLab DAST\"."
license: MIT
---

# GitLab CI/CD Expert

This skill covers GitLab CI/CD across recent versions (18.x). GitLab CI is tightly integrated into GitLab — source code, CI/CD, container registry, security scanning, and deployment are unified in one platform. Configuration is via `.gitlab-ci.yml` in the repository root. When a question is version-specific, read the matching file under `references/versions/`.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md` for pipeline failures, runner issues, YAML errors
   - **Architecture** -- Load `references/architecture.md` for runner architecture, executor types, pipeline types, CI/CD components
   - **Best practices** -- Load `references/best-practices.md` for pipeline design, security scanning, caching, performance

2. **Load context** -- Read the relevant reference file.

3. **Analyze** -- Apply GitLab CI-specific reasoning. Consider pipeline type (basic, DAG, parent-child, multi-project), runner executor, and caching scope.

4. **Recommend** -- Provide `.gitlab-ci.yml` examples with explanations.

5. **Verify** -- Suggest validation (`gitlab-ci-lint`, CI Lint API, pipeline visualization in the UI).

## Core Concepts

### Pipeline Structure

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

variables:
  NODE_VERSION: "22"

default:
  image: node:${NODE_VERSION}
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test:unit:
  stage: test
  script:
    - npm test
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'

test:e2e:
  stage: test
  script:
    - npm run test:e2e
  services:
    - postgres:16
  variables:
    POSTGRES_DB: test
    POSTGRES_USER: runner
    POSTGRES_PASSWORD: secret

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
    url: https://myapp.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
```

### Key Directives

| Directive | Purpose | Example |
|---|---|---|
| `stages` | Define pipeline stages and their order | `stages: [build, test, deploy]` |
| `image` | Docker image for the job | `image: node:22` |
| `script` | Shell commands to execute | `script: [npm ci, npm test]` |
| `artifacts` | Files to pass between jobs | `artifacts: { paths: [dist/] }` |
| `cache` | Persistent files across pipeline runs | `cache: { paths: [node_modules/] }` |
| `services` | Docker services (databases, etc.) | `services: [postgres:16, redis:8]` |
| `variables` | Environment variables | `variables: { NODE_ENV: production }` |
| `rules` | When to run the job (replaces `only/except`) | `rules: [{ if: '$CI_COMMIT_BRANCH == "main"' }]` |
| `needs` | DAG dependencies (skip stage ordering) | `needs: [build]` |
| `environment` | Deployment target | `environment: { name: staging }` |
| `trigger` | Trigger child/multi-project pipelines | `trigger: { include: child.yml }` |
| `extends` | Inherit from another job definition | `extends: .deploy-template` |
| `include` | Include external YAML files | `include: { template: Security/SAST.gitlab-ci.yml }` |

### Rules (Conditional Execution)

```yaml
deploy:
  rules:
    - if: $CI_COMMIT_TAG                     # Run on tags
      when: always
    - if: $CI_COMMIT_BRANCH == "main"        # Manual on main
      when: manual
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"  # Run on MRs
    - when: never                            # Default: don't run
```

### Pipeline Types

| Type | How | When |
|---|---|---|
| **Basic** | Linear stages: build → test → deploy | Simple projects |
| **DAG** | `needs:` keyword bypasses stage ordering | Complex dependencies, faster pipelines |
| **Parent-Child** | `trigger: { include: ... }` spawns child pipeline | Monorepos, modular config |
| **Multi-Project** | `trigger: { project: org/other-repo }` triggers another project | Cross-repo dependencies |
| **Merge Request** | `rules: [{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]` | PR-style CI |

### DAG Pipelines

```yaml
build:frontend:
  stage: build
  script: npm run build:frontend

build:backend:
  stage: build
  script: npm run build:backend

test:frontend:
  stage: test
  needs: [build:frontend]    # Starts as soon as build:frontend finishes
  script: npm run test:frontend

test:backend:
  stage: test
  needs: [build:backend]     # Doesn't wait for build:frontend
  script: npm run test:backend

deploy:
  stage: deploy
  needs: [test:frontend, test:backend]
  script: ./deploy.sh
```

## Runners and Executors

| Executor | Isolation | Speed | Use Case |
|---|---|---|---|
| **Docker** | Container per job | Fast | Default for most workloads |
| **Docker Machine** | VM per job (autoscaling) | Medium | Autoscaled cloud runners |
| **Kubernetes** | Pod per job | Medium | K8s-native, autoscaling |
| **Shell** | None (runs on host) | Fastest | Simple, trusted environments |
| **Virtual Machine** | Full VM isolation | Slowest | macOS, Windows, security-critical |
| **Instance** | Fleeting VM per job | Medium | Cloud-native autoscaling (replaces Docker Machine) |

### Runner Registration

```bash
# Register a runner
gitlab-runner register \
  --url https://gitlab.example.com \
  --token <RUNNER_TOKEN> \
  --executor docker \
  --docker-image alpine:latest

# Verify runner connectivity
gitlab-runner verify
gitlab-runner status
```

## CI/CD Components (Reusable Templates)

```yaml
# Include a CI/CD component from the catalog
include:
  - component: gitlab.com/components/sast@1.0
    inputs:
      stage: test

# Include project templates
include:
  - project: 'mygroup/ci-templates'
    ref: main
    file: '/templates/docker-build.yml'

# Include GitLab-maintained templates
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
```

### Template Inheritance

```yaml
# Define reusable templates with dot-prefix (hidden jobs)
.deploy-template:
  script:
    - echo "Deploying to $ENVIRONMENT"
    - ./deploy.sh
  environment:
    name: $ENVIRONMENT

deploy:staging:
  extends: .deploy-template
  variables:
    ENVIRONMENT: staging
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:production:
  extends: .deploy-template
  variables:
    ENVIRONMENT: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
```

## Security Scanning Integration

GitLab includes built-in security scanning:

```yaml
include:
  - template: Security/SAST.gitlab-ci.yml              # Static analysis
  - template: Security/Dependency-Scanning.gitlab-ci.yml # Dependency vulnerabilities
  - template: Security/Container-Scanning.gitlab-ci.yml  # Container image scanning
  - template: Security/DAST.gitlab-ci.yml               # Dynamic testing
  - template: Security/Secret-Detection.gitlab-ci.yml   # Secrets in code
```

Results appear in the merge request security widget and the security dashboard.

## Version-Specific Guidance

| Version | Reference | What's new |
|---|---|---|
| 18.7 | `references/versions/18.7.md` | CI/CD Catalog reaches GA, pipeline execution policies, tighter job token scoping, runner fleet visibility dashboard |
| 18.8 | `references/versions/18.8.md` | CI Steps (beta), pipeline mini-graph improvements, component testing framework, Kubernetes executor enhancements |
| 18.9 | `references/versions/18.9.md` | CI Steps improvements, pipeline composition enhancements, advanced caching strategies, security policy automation |

## Reference Files

- `references/architecture.md` — Runner internals, executor deep dive, pipeline processing, CI/CD variables hierarchy, component catalog architecture
- `references/best-practices.md` — Pipeline optimization, caching strategies, security scanning integration, monorepo patterns, compliance pipelines
- `references/diagnostics.md` — Pipeline debugging, runner troubleshooting, YAML validation, cache issues, artifact problems