| name | gitlab-cicd |
| description | GitLab CI/CD pipeline expert for creating and configuring `.gitlab-ci.yml` files. Use when working with GitLab pipelines for: (1) Creating or editing `.gitlab-ci.yml` pipeline configurations, (2) Configuring jobs, stages, rules, `needs`, and includes, (3) Setting up CI/CD variables (masked, protected, external secrets), (4) Configuring caching and artifacts, (5) Setting up pipeline triggers, schedules, child/multi-project pipelines, (6) Runner configuration and image handling, (7) Security scanning integration (SAST, secret detection, dependency scanning), (8) Pipeline speed optimization and best practices, (9) Troubleshooting pipeline failures.
|
GitLab CI/CD
Quick Start
Minimum viable .gitlab-ci.yml:
stages: [build, test, deploy]
default:
image: node:20-alpine
before_script: [npm ci]
build:
stage: build
script: npm run build
artifacts:
paths: [dist/]
expire_in: 1 week
test:
stage: test
needs: [build]
script: npm test
artifacts:
reports:
junit: junit.xml
deploy:
stage: deploy
script: ./deploy.sh
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
environment:
name: production
url: https://example.com
Key Concepts
- Stages define execution order; jobs within a stage run in parallel
needs: breaks stage ordering — use it for DAG execution (jobs run as soon as their deps finish)rules: controls when a job is included (preferred over deprecated only:/except:)default: sets defaults for all jobs (never put image:, cache:, etc. at top level — deprecated).pre / .post are reserved stages that always run first/last
Reference Files
Load these as needed based on the task:
references/pipeline-config.md
Full .gitlab-ci.yml syntax reference: global keywords, job keywords, rules, needs, include, child/multi-project pipelines, parameterized components, and predefined variables.
Read when: Creating or editing pipeline config, working with needs/DAG pipelines, using include:, configuring parallel matrix jobs, or looking up predefined variable names.
references/variables.md
CI/CD variables: types (variable vs. file), defining in YAML and UI, precedence order, masking/protecting variables, external secrets (Vault/GCP/Azure/AWS), and caveats.
Read when: Working with CI/CD variables, secrets, masked/protected variables, or external secret managers.
references/caching-artifacts.md
Caching (keys, policies, multiple caches, fallbacks) and artifacts (upload, download, access control, artifact reports for JUnit/coverage/SAST/dotenv).
Read when: Setting up dependency caching, configuring artifacts, passing data between jobs, or working with test/coverage reports.
references/runners.md
Runner types, executors (Docker vs. Shell vs. Kubernetes), image pull policies, Docker-in-Docker vs. Kaniko, private registries, runner registration, and security.
Read when: Configuring runner tags, setting up Docker image handling, working with private registries, or building/pushing Docker images in CI.
references/triggers-pipelines.md
Pipeline types (basic, DAG, MR, parent-child, multi-project), API triggers, trigger: keyword, scheduled pipelines, MR pipelines, skipping pipelines, and manual jobs.
Read when: Setting up pipeline triggers, scheduled pipelines, MR pipelines, child/multi-project pipelines, or debugging $CI_PIPELINE_SOURCE values.
references/security.md
Security scanning templates (SAST, secret detection, container scanning), variable protection patterns, runner hardening, container security (Kaniko, non-root), supply chain security (image pinning, integrity verification), and a security checklist.
Read when: Adding security scanning, hardening the pipeline, configuring protected environments, or reviewing security posture.
references/optimization.md
Pipeline speed optimization: DAG with needs:, interruptible/auto_cancel, file-based job skipping, caching patterns, Docker image optimization, parallelization (parallel: N and matrix), resource groups, and general best practices.
Read when: Improving pipeline speed, reducing CI costs, parallelizing test runs, or identifying bottlenecks.
Common Patterns
Prevent Duplicate Pipelines (branch + MR)
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
when: never
- if: $CI_COMMIT_BRANCH
Run Job Only on Main Branch
deploy:
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- when: never
Only Run When Relevant Files Change
test-backend:
rules:
- changes: [backend/**, requirements.txt]
- when: never
Pass Data Between Jobs
build:
script:
- echo "IMAGE_TAG=$(git rev-parse --short HEAD)" >> build.env
artifacts:
reports:
dotenv: build.env
deploy:
needs: [build]
script: deploy.sh $IMAGE_TAG
Monorepo: Trigger Child Pipelines Per Service
trigger-api:
trigger:
include: api/.gitlab-ci.yml
strategy: depend
trigger-web:
trigger:
include: web/.gitlab-ci.yml
strategy: depend
rules:
- changes: [web/**]
Manual Production Deploy with Confirmation
deploy-production:
when: manual
manual_confirmation: "Deploy to PRODUCTION?"
environment:
name: production
url: https://example.com
rules:
- if: $CI_COMMIT_BRANCH == "main"
Security Essentials
- Store secrets in masked + protected UI variables, never in
.gitlab-ci.yml
- Use protected environments to gate production deployments by role
- Include
Security/SAST.gitlab-ci.yml and Security/Secret-Detection.gitlab-ci.yml at minimum
- Prefer Kaniko over Docker-in-Docker (no privileged runner required)
- Pin image tags to specific versions (not
:latest); use digest pinning for highest assurance
- Review
.gitlab-ci.yml changes in MRs with CODEOWNERS + required approvals
Speed Essentials
- Use
needs: to unlock DAG execution — biggest single speed win
- Mark build/test jobs
interruptible: true with workflow.auto_cancel.on_new_commit: interruptible
- Use
cache.key.files: [lockfile] for automatic cache invalidation
- Skip jobs with
rules.changes: when unrelated files changed
- Set
expire_in: on all artifacts; use when: on_failure for debugging-only artifacts
