基本语法

job-b:
  stage: deploy
  needs:
    - job: job-a # 必须指定作业名称
    - job: job-c
      artifacts: false # 可选：不从 job-c 下载产物

关键规则

• needs: 可以引用任何阶段中的作业，包括同一阶段甚至更晚的阶段（使用 needs: [] 表示立即开始，无依赖）
• 每个作业的最大 needs: 条目数：50（可由管理员配置，默认为 50）
• 如果 needs: 为空 (needs: [])，作业在流水线开始时立即启动
• 带有 needs: 的作业默认跳过从非列出作业下载产物
• 你仍然可以将 needs: 与 stage: 结合使用以保持组织清晰——阶段仍有助于 UI 显示

立即启动作业（无先决条件）

lint:
  stage: test
  needs: [] # 流水线一开始就运行，无论其他作业如何
  script: ./run-lint.sh

parallel: — 简单的测试分片

将单个作业拆分为 N 个并发运行的克隆。GitLab 会自动注入 $CI_NODE_INDEX（从 1 开始）和 $CI_NODE_TOTAL。

test:
  stage: test
  parallel: 5 # 创建 test 1/5, test 2/5, ... test 5/5
  script:
    - bundle exec rspec --format progress \
      $(ruby -e "
      files = Dir['spec/**/*_spec.rb']
      chunk = files.each_slice((files.size.to_f / $CI_NODE_TOTAL).ceil).to_a
      puts chunk[$CI_NODE_INDEX - 1].join(' ')
      ")

最大值：200 个并行实例。

parallel:matrix — 多维作业

在一组变量组合上运行相同的作业配置。每个组合成为一个单独的作业，命名为 job-name: [VAL1, VAL2]。

build:
  stage: build
  image: python:$VERSION
  script: ./build.sh
  parallel:
    matrix:
      - VERSION: ["3.10", "3.11", "3.12"]
        PLATFORM: [linux, macos]

这将创建 6 个作业：每个 VERSION × PLATFORM 的排列组合。

限制：矩阵生成的总作业数最大为 200。请相应规划你的维度——在添加值之前检查计算。

needs: + parallel:matrix — 带矩阵的 DAG

引用矩阵作业的 ALL 实例

deploy:
  stage: deploy
  needs:
    - job: build
      parallel:
        matrix:
          - VERSION: ["3.10", "3.11", "3.12"]
            PLATFORM: [linux, macos]

Deploy 等待所有 6 个 build 矩阵作业。

引用一个 SPECIFIC 矩阵实例

deploy-linux-310:
  stage: deploy
  needs:
    - job: build
      parallel:
        matrix:
          - VERSION: "3.10"
            PLATFORM: linux

使用矩阵表达式进行 1:1 映射 (GitLab 17+)

使用 $[[ matrix.IDENTIFIER ]] 创建自动的 1:1 依赖关系——每个测试实例只等待其匹配的构建实例：

build:
  stage: build
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]
  script: ./build.sh $OS $ARCH

test:
  stage: test
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]
  needs:
    - job: build
      parallel:
        matrix:
          - OS: ["$[[ matrix.OS ]]"]
            ARCH: ["$[[ matrix.ARCH ]]"]
  script: ./test.sh $OS $ARCH

test: [ubuntu, amd64] 只等待 build: [ubuntu, amd64]——而不是其他 3 个构建作业。这是大型矩阵流水线最强大的模式。

使用 YAML 锚点和 !reference 的 DRY 模式

避免在多个作业中重复相同的 parallel:matrix 块。

YAML 锚点

.matrix: &matrix
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]

build:
  stage: build
  <<: *matrix
  script: ./build.sh

test:
  stage: test
  <<: *matrix
  needs:
    - job: build
      parallel:
        matrix:
          - OS: ["$[[ matrix.OS ]]"]
            ARCH: ["$[[ matrix.ARCH ]]"]
  script: ./test.sh

⚠️ extends: 合并哈希但不合并数组——对于 script: 块或数组覆盖，建议使用 YAML 锚点或 !reference。

完整示例：优化的多语言流水线

stages:
  - lint
  - build
  - test
  - deploy

# 立即开始——无依赖
lint:
  stage: lint
  needs: []
  script: ./run-linters.sh

# 矩阵构建：6 个作业 (3 个版本 × 2 个平台)
build:
  stage: build
  needs: [lint]
  parallel:
    matrix:
      - LANG_VERSION: ["3.10", "3.11", "3.12"]
        PLATFORM: [linux, windows]
  script: ./build.sh $LANG_VERSION $PLATFORM
  artifacts:
    paths: [dist/]

# 通过矩阵表达式实现 1:1 的测试-构建对应
unit-test:
  stage: test
  parallel:
    matrix:
      - LANG_VERSION: ["3.10", "3.11", "3.12"]
        PLATFORM: [linux, windows]
  needs:
    - job: build
      parallel:
        matrix:
          - LANG_VERSION: ["$[[ matrix.LANG_VERSION ]]"]
            PLATFORM: ["$[[ matrix.PLATFORM ]]"]
  script: ./test.sh $LANG_VERSION $PLATFORM

# 集成测试的并行分片（独立）
integration-test:
  stage: test
  needs: [] # 立即开始，不等待构建
  parallel: 4
  script: ./integration-test.sh

# 仅在所有单元测试和集成测试通过后部署
deploy:
  stage: deploy
  needs:
    - job: unit-test
      parallel:
        matrix:
          - LANG_VERSION: ["3.10", "3.11", "3.12"]
            PLATFORM: [linux, windows]
    - job: integration-test
  script: ./deploy.sh

常见陷阱与修复方法

决策指南：使用哪种模式？

需要并行化吗？
├── 相同作业，拆分工作负载 → parallel: N  (使用 $CI_NODE_INDEX/$CI_NODE_TOTAL)
├── 相同作业，不同环境/版本 → parallel:matrix
└── 不同作业 → 定义单独的作业，用 needs: 链接

需要跨矩阵依赖吗？
├── 一个作业需要 ALL 矩阵实例 → needs: 带完整矩阵列表
├── 一个作业需要 ONE 特定实例 → needs: 带精确矩阵值
└── N:1 相同形状映射 → 使用 $[[ matrix.IDENTIFIER ]] 表达式 (GitLab 17+)

需要减少流水线时间吗？
├── 没有真实依赖的作业 → needs: [] (立即运行)
├── 长的测试套件 → parallel: N 分片
└── 多环境构建 + 测试 → 矩阵 + 矩阵表达式实现 1:1 DAG

输出格式

编写或审查 .gitlab-ci.yml 片段时：

1. 始终包含 stages: 声明以保持清晰
2. 注释非显而易见的 needs: 关系
3. 优先使用 $[[ matrix.X ]] 表达式，而非手动列出所有组合
4. 当作业产生被依赖项使用的输出时，包含产物处理 (artifacts: 块)
5. 验证计算：使用 parallel:matrix 时列出总作业数（必须 ≤ 200）

更多详情，请在处理复杂的嵌套 DAG、带有子流水线的 trigger: 或跨流水线依赖 needs:pipeline 时阅读 references/gitlab-dag-advanced.md。

每周安装数

1

代码仓库

bsene/skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1

needs: Keyword Reference

Basic syntax

job-b:
  stage: deploy
  needs:
    - job: job-a # must specify job name
    - job: job-c
      artifacts: false # optional: don't download artifacts from job-c

Key rules

• needs: can reference jobs in any stage , including the same stage or even a later stage (use needs: [] to start immediately with no dependencies)
• Max needs: entries per job: 50 (configurable by admins, default 50)
• If needs: is empty (needs: []), the job starts immediately when the pipeline begins
• A job with needs: skips artifact download from non-listed jobs by default
• You can still combine needs: with stage: for organizational clarity — stages still help the UI display

Start a job immediately (no prerequisites)

lint:
  stage: test
  needs: [] # runs as soon as the pipeline starts, regardless of other jobs
  script: ./run-lint.sh

parallel: — Simple Test Sharding

Split a single job into N clones running concurrently. GitLab injects $CI_NODE_INDEX (1-based) and $CI_NODE_TOTAL automatically.

test:
  stage: test
  parallel: 5 # creates test 1/5, test 2/5, ... test 5/5
  script:
    - bundle exec rspec --format progress \
      $(ruby -e "
      files = Dir['spec/**/*_spec.rb']
      chunk = files.each_slice((files.size.to_f / $CI_NODE_TOTAL).ceil).to_a
      puts chunk[$CI_NODE_INDEX - 1].join(' ')
      ")

Max value: 200 parallel instances.

parallel:matrix — Multi-Dimensional Jobs

Run the same job configuration across a set of variable combinations. Each combination becomes a separate job named job-name: [VAL1, VAL2].

build:
  stage: build
  image: python:$VERSION
  script: ./build.sh
  parallel:
    matrix:
      - VERSION: ["3.10", "3.11", "3.12"]
        PLATFORM: [linux, macos]

This creates 6 jobs: every VERSION × PLATFORM permutation.

Limit : max 200 jobs total from a matrix. Plan your dimensions accordingly — check the math before adding values.

needs: + parallel:matrix — DAG with Matrix

Reference ALL instances of a matrix job

deploy:
  stage: deploy
  needs:
    - job: build
      parallel:
        matrix:
          - VERSION: ["3.10", "3.11", "3.12"]
            PLATFORM: [linux, macos]

Deploy waits for all 6 build matrix jobs.

Reference a SPECIFIC matrix instance

deploy-linux-310:
  stage: deploy
  needs:
    - job: build
      parallel:
        matrix:
          - VERSION: "3.10"
            PLATFORM: linux

1:1 Mapping with Matrix Expressions (GitLab 17+)

Use $[[ matrix.IDENTIFIER ]] to create automatic 1:1 dependencies — each test instance only waits for its matching build instance:

build:
  stage: build
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]
  script: ./build.sh $OS $ARCH

test:
  stage: test
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]
  needs:
    - job: build
      parallel:
        matrix:
          - OS: ["$[[ matrix.OS ]]"]
            ARCH: ["$[[ matrix.ARCH ]]"]
  script: ./test.sh $OS $ARCH

test: [ubuntu, amd64] only waits for build: [ubuntu, amd64] — not the other 3 build jobs. This is the most powerful pattern for large matrix pipelines.

DRY Patterns with YAML Anchors & !reference

Avoid repeating the same parallel:matrix block across multiple jobs.

YAML Anchors

.matrix: &matrix
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]

build:
  stage: build
  <<: *matrix
  script: ./build.sh

test:
  stage: test
  <<: *matrix
  needs:
    - job: build
      parallel:
        matrix:
          - OS: ["$[[ matrix.OS ]]"]
            ARCH: ["$[[ matrix.ARCH ]]"]
  script: ./test.sh

⚠️ extends: merges hashes but not arrays — for script: blocks or array overrides, prefer YAML anchors or !reference.

Full Example: Optimized Multi-Language Pipeline

stages:
  - lint
  - build
  - test
  - deploy

# Starts immediately — no dependencies
lint:
  stage: lint
  needs: []
  script: ./run-linters.sh

# Matrix build: 6 jobs (3 versions × 2 platforms)
build:
  stage: build
  needs: [lint]
  parallel:
    matrix:
      - LANG_VERSION: ["3.10", "3.11", "3.12"]
        PLATFORM: [linux, windows]
  script: ./build.sh $LANG_VERSION $PLATFORM
  artifacts:
    paths: [dist/]

# 1:1 test-per-build via matrix expressions
unit-test:
  stage: test
  parallel:
    matrix:
      - LANG_VERSION: ["3.10", "3.11", "3.12"]
        PLATFORM: [linux, windows]
  needs:
    - job: build
      parallel:
        matrix:
          - LANG_VERSION: ["$[[ matrix.LANG_VERSION ]]"]
            PLATFORM: ["$[[ matrix.PLATFORM ]]"]
  script: ./test.sh $LANG_VERSION $PLATFORM

# Parallel sharding of integration tests (independent)
integration-test:
  stage: test
  needs: [] # starts immediately, doesn't wait for build
  parallel: 4
  script: ./integration-test.sh

# Deploy only after all unit-tests and integration-tests pass
deploy:
  stage: deploy
  needs:
    - job: unit-test
      parallel:
        matrix:
          - LANG_VERSION: ["3.10", "3.11", "3.12"]
            PLATFORM: [linux, windows]
    - job: integration-test
  script: ./deploy.sh

Common Pitfalls & Fixes

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

Output Format

When writing or reviewing .gitlab-ci.yml snippets:

1. Always include stages: declaration for clarity
2. Comment non-obvious needs: relationships
3. Prefer $[[ matrix.X ]] expressions over manually listing all combinations
4. Include artifact handling (artifacts: block) when jobs produce outputs consumed by dependents
5. Validate the math: list total job count when using parallel:matrix (must be ≤ 200)

For more details, read references/gitlab-dag-advanced.md when handling complex nested DAGs, trigger: with child pipelines, or needs:pipeline cross-pipeline dependencies.

Weekly Installs

1

Repository

bsene/skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1