Gitlab Cicd

GitLab CI/CD

Expert-level guidance for GitLab CI/CD pipeline configuration, development, optimization, debugging, and best practices. Covers GitLab 9.0 through 18.x with version-specific annotations.

When to Use This Skill

• Configuring or modifying .gitlab-ci.yml files
• Debugging pipeline failures or unexpected job behavior
• Optimizing pipeline performance and compute minutes
• Setting up CI/CD components and include templates
• Managing runner infrastructure and autoscaling
• Implementing deployment strategies and environment lifecycle
• Configuring secrets, security scanning, and compliance
• Implementing semantic-release automation

Do Not Use This Skill When

• Working with GitHub Actions or other non-GitLab CI systems
• Managing GitLab instance administration (not CI/CD pipeline config)
• Writing application code unrelated to CI/CD

Quick Reference — Top 20 Keywords

Quick Reference — Top 10 Predefined Variables

For the complete 170+ variable reference, see predefined variables.

Quick-Start Example

# Minimal pipeline — see references/ for each topic
stages: [build, test, deploy]                    # → types-and-triggers.md

variables:                                        # → variables/definition.md
  NODE_VERSION: "20"

default:
  image: node:${NODE_VERSION}
  cache:                                          # → jobs/caching.md
    key:
      files: [package-lock.json]
    paths: [node_modules/]

build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:                                      # → jobs/artifacts.md
    paths: [dist/]
    expire_in: 1 week

test:
  stage: test
  script: npm test
  coverage: '/Statements\s*:\s*(\d+\.?\d*)%/'    # → jobs/testing.md
  needs: [build]                                  # → jobs/execution-flow.md

deploy:
  stage: deploy
  script: ./deploy.sh
  environment:                                    # → pipelines/environments.md
    name: production
  rules:                                          # → yaml/rules-patterns.md
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  needs: [test]

Pipeline Configuration

GitLab supports multiple pipeline types with distinct triggering rules and variable availability.

Key gotcha: CI_MERGE_REQUEST_* variables are only available when CI_PIPELINE_SOURCE=merge_request_event. Use workflow:rules to prevent duplicate branch+MR pipelines.

References:

• Pipeline Types & Triggers
• Merge Request Pipelines — detached, merged results, merge trains, fork handling
• Downstream Pipelines — parent-child, multi-project, dynamic child
• Monorepo Strategies — rules:changes, per-service child pipelines
• Pipeline Optimization — DAG, parallelism, compute minutes
• Scheduled Pipelines — cron syntax, schedule-only patterns
• Manual Gates — when:manual, approvals, deploy freezes
• Cross-Project Pipelines — multi-project triggers, artifact sharing
• Notifications & Badges — pipeline badges, email/Slack integration

YAML Authoring

Pipeline YAML supports composition patterns for DRY, maintainable configurations.

Key gotcha: YAML anchors do NOT work across include boundaries — use extends or !reference instead.

References:

• Keyword Reference — full .gitlab-ci.yml keyword documentation
• Rules Patterns — rules:if, rules:changes, rules:exists
• YAML Composition — anchors, extends, !reference, merge keys
• Workflow Rules — workflow:rules, auto_cancel, naming
• YAML Optimization — DRY pipeline design patterns

Variables

Variables follow an 11-level precedence hierarchy — knowing the order prevents hours of debugging.

Precedence (highest → lowest):

1. Pipeline execution policy variables
2. Scan execution policy variables
3. Pipeline variables (trigger, scheduled, manual, API)
4. Project variables (UI/API)
5. Group variables (inherited, closest subgroup wins)
6. Instance variables
7. dotenv report variables
8. Job-level YAML variables:
9. Default (global) YAML variables:
10. Deployment variables
11. Predefined variables

Note: trigger:forward:pipeline_variables: true elevates parent YAML variables to pipeline variable precedence (level 3) in downstream pipelines. It is a mechanism, not a separate precedence level.

Key gotcha: Variables defined in rules:variables override job-level variables but only when that rule matches.

References:

• Predefined Variables — 170+ variables by category and version
• Variable Precedence — 11-level hierarchy with override examples
• Masking & Protection — masking rules, ≥8 chars, protected scoping
• Variable Scopes — expansion in rules vs script vs services
• Variable Definition — YAML, UI, API, options, description

Jobs & Execution

Key gotcha: cache is for speed (may miss); artifacts are for correctness (guaranteed). Don't use cache to pass build outputs between jobs — use artifacts.

References:

• Testing Strategies — JUnit, coverage, quality reports
• Caching — cache:key:files, fallback_keys, distributed cache
• Artifacts — expire_in, expose_as, cross-pipeline sharing
• Execution Flow — needs:, dependencies, DAG patterns
• Docker Builds — DinD, Kaniko, Buildah, multi-stage
• Git Strategies — GIT_STRATEGY, GIT_DEPTH, submodules
• Retry & Resilience — retry:when, allow_failure, timeout

Runner Infrastructure

Runners execute jobs. Executor choice determines security model, performance, and isolation.

Key gotcha: Docker-in-Docker (dind) requires privileged: true — significant security risk. Prefer Kaniko for container builds when possible.

References:

• Runner Architecture — manager model, executor types, compatibility
• Executors — Docker, K8s, shell config and comparison
• Autoscaling — docker-autoscaler, fleeting, scaling policies
• Runner Security — tokens, allowed_images, hardening
• Performance — concurrent, check_interval, tuning
• Fleet Management — config.toml, Prometheus metrics

CI/CD Components

Components are reusable pipeline building blocks published to the CI/CD Catalog (GitLab 17.0+).

include:
  - component: $CI_SERVER_FQDN/my-org/my-component@1.2.0
    inputs:
      stage: test
      scan_level: full

Key gotcha: Always pin component versions (@1.2.0 or @1 for major). Unpinned components are a supply-chain risk.

References:

• Component Authoring — project structure, spec:inputs, Catalog
• Catalog — discovery, version pinning, evaluation
• Inputs — types, validation, defaults
• Testing — self-referencing, integration tests
• Security — pinning audit, include:integrity

Semantic Release

Automated versioning with @semantic-release/gitlab and the to-be-continuous component.

Token setup: Requires GITLAB_TOKEN (project access token with api scope) or GL_TOKEN. Must be masked and protected.

Key gotcha: Set GIT_DEPTH: 0 in the release job — shallow clones break commit analysis.

References:

• GitLab Integration — plugin lifecycle, TBC, tokens
• Configuration — .releaserc, presets, hooks, GPG
• Testing — dry-run, verification

Deployment & Environments

Key gotcha: Always set auto_stop_in on dynamic environments. Without it, review apps accumulate and leak resources.

References:

• Deployment Strategies — blue-green, canary, rolling, feature flags
• Dynamic Environments — review apps, auto_stop, cleanup
• Infrastructure as Code — Terraform/OpenTofu, state
• Release Automation — changelog, orchestration

Security

Key gotcha: CI_JOB_TOKEN default scope allows access to all reachable projects. Restrict it via Settings > CI/CD > Token Access.

References:

• Secrets Management — Vault, GCP, Azure, AWS, OIDC
• Security Scanning — SAST, DAST, container, dependency
• Compliance — frameworks, audit trails, governance
• Pipeline Security — CI_JOB_TOKEN scoping, protected runners, fork safety

Troubleshooting

Debugging decision tree:

1. YAML syntax error? → Use Pipeline Editor or CI Lint API
2. Job not starting? → Check rules: evaluation — View "merged YAML" in Pipeline Editor
3. Variable not expanding? → Check scopes and precedence
4. Cache miss? → Verify cache:key matches — check runner cache backend
5. Artifact not found? → Check expire_in, dependencies:, and needs:artifacts:
6. Runner issues? → Check tags, runner availability, executor config
7. Need verbose output? → Set CI_DEBUG_TRACE=true (⚠️ exposes secrets)

References:

• Troubleshooting Guide — editor, lint, debug trace, common errors
• FAQ & Gotchas — top 25+ categorized gotchas with fixes

Output Formats

When producing specific types of analysis, use the corresponding output format spec:

Version Compatibility

Key feature introductions across GitLab versions:

Related Resources

• GitLab CI/CD Documentation
• .gitlab-ci.yml Reference
• Predefined Variables
• CI/CD Component Catalog
• GitLab Runner Documentation

Workspace Examples

Annotated analyses of real pipelines from this workspace:

• MAP Terragrunt Pipeline — component includes, MegaLinter, release automation
• Component Include Patterns — template structure, spec:inputs usage