bsene GitLab DAG & Parallelism Skill
Use this skill to design, generate, review, and fix GitLab CI/CD pipeline configurations
that leverage DAG (needs:) and parallelism (parallel:, parallel:matrix).
Core Concepts
Standard Stage Order vs DAG
Without DAG: Jobs execute strictly stage-by-stage. All jobs in stage N must complete before stage N+1 starts — even if only one job in a stage is the actual prerequisite.
With DAG (needs:): Jobs start as soon as their specific dependencies finish, skipping the stage-order wait. This can dramatically reduce total pipeline time.
# Standard (slow): test waits for ALL build jobs to finish
stages: [build, test, deploy]
build-frontend:
stage: build
build-backend:
stage: build # runs in parallel with build-frontend
test-frontend:
stage: test # waits for BOTH build jobs even though it only needs build-frontend
# DAG (fast): test-frontend starts the moment build-frontend finishes
test-frontend:
stage: test
needs: [build-frontend] # ignores build-backend's status entirely
Read On Demand
| Read When | File |
|---|---|
Writing needs: dependencies, artifact control, immediate-start jobs |
needs: Keyword Reference |
Using parallel:, parallel:matrix, or 1:1 matrix expressions |
Parallel & Matrix Patterns |
DRY patterns (YAML anchors, !reference), full pipeline examples |
DRY Patterns & Examples |
Decision Guide: Which Pattern to Use?
Need to parallelize?
├── Same job, split workload → parallel: N (use $CI_NODE_INDEX/$CI_NODE_TOTAL)
├── Same job, different envs/versions → parallel:matrix
└── Different jobs → define separate jobs, link with needs:
Need cross-matrix dependencies?
├── One job needs ALL matrix instances → needs: with full matrix list
├── One job needs ONE specific instance → needs: with exact matrix values
└── N:1 same-shape mapping → use $[[ matrix.IDENTIFIER ]] expressions (GitLab 17+)
Need to reduce pipeline time?
├── Jobs without real dependencies → needs: [] (run immediately)
├── Long test suite → parallel: N sharding
└── Multi-env builds + tests → matrix + matrix expressions for 1:1 DAG
Common Pitfalls & Fixes
| Problem | Cause | Fix |
|---|---|---|
| Job still waits for unrelated jobs | Not using needs: |
Add needs: listing only direct prerequisites |
parallel:matrix generates too many jobs |
Cartesian product exceeds 200 | Reduce dimensions or split into separate job groups |
needs: breaks artifact download |
Non-listed jobs' artifacts are skipped | Add artifacts: true explicitly for needed artifacts |
Matrix expression $[[ matrix.X ]] not working |
GitLab version < 17 or typo in identifier | Check GitLab version; identifiers are case-sensitive |
extends: silently drops array values |
extends merges hashes, not arrays |
Use YAML anchors (&anchor / <<: *anchor) for arrays |
| Job starts too early | needs: [] used unintentionally |
Remove needs: [] if the job should wait for a stage |
Output Format
When writing or reviewing .gitlab-ci.yml snippets:
- Always include
stages:declaration for clarity - Comment non-obvious
needs:relationships - Prefer
$[[ matrix.X ]]expressions over manually listing all combinations - Include artifact handling (
artifacts:block) when jobs produce outputs consumed by dependents - Validate the math: list total job count when using
parallel:matrix(must be ≤ 200)
Benchmark
Scenario: .benchmarks/scenarios/gitlab-dag-001-pipeline-dag.md · Run: 2026-08-31 · Log: .benchmarks/runs/2026-08-31/gitlab-dag-001-pipeline-dag.json
| Model | Without | With | Delta |
|---|---|---|---|
| claude-opus-4-8 | 67% | 100% | +33% |
| claude-sonnet-4-6 | 67% | 100% | +33% |
| claude-haiku-4-5 | 50% | 100% | +50% |
PASS (run 2026-08-31). Lift on all models; baselines flatten dependency structure that the DAG view makes explicit. Gate per
.agents/skills/skill-optimizer/rules/release-gates.md.