gitlab-ci

GitLab CI/CD 流水线配置

补充说明

GitLab CI/CD 读取仓库根目录的 .gitlab-ci.yml，由 GitLab Runner 执行 job。它支持 stage 顺序、DAG 依赖、规则匹配、缓存与制品，配置能力比 GitHub Actions 更集中。

常用示例

glab ci lint
glab ci run
glab ci status
glab ci view
glab pipeline list

最小配置：

stages: [build, test, deploy]

default:
  image: node:24
  cache:
    key:
      files: [package-lock.json]
    paths: [.npm/]

build:
  stage: build
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build
  artifacts:
    paths: [dist/]
    expire_in: 1 week

test:
  stage: test
  needs: [build]
  script:
    - npm test

deploy:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
  script:
    - ./deploy.sh

易错点与排错

• rules 是新写法，only/except 是旧写法；同一 job 不要混用，否则行为难预测。
• needs 会打破 stage 顺序形成 DAG；依赖的 job 不存在或未产生制品会失败。
• cache 是尽力而为，可能丢失；构建产物要放 artifacts，不要只依赖 cache。
• artifacts 默认只在同一 pipeline 内可用；跨 pipeline 需要 dependencies 或外部存储。
• 受保护分支和受保护变量是两道独立门槛；普通分支拿不到受保护变量。
• Runner 的 tag 不匹配时 job 会一直 pending；先看 Runner 的标签和并发。
• $CI_* 变量在 MR pipeline 和分支 pipeline 中取值不同；写规则前先打印确认。
• 变量默认可能被展开或屏蔽；密钥用 masked/protected 变量，不要写进 YAML。
• allow_failure 会让失败 job 不阻断流水线；别用它掩盖真正的错误。
• include 的路径和 ref 要明确；远程 include 会引入外部变更风险。

相关命令

• gitlab-runner — Runner 管理
• glab — GitLab CLI
• github-actions — GitHub 的同类方案

读完自测

合上页面，先回答，再展开对照。

1. 同一个 job 里可以混用 rules 和 only/except 吗？
2. cache 能当作构建产物在不同 job 间可靠传递吗？
3. job 一直处于 pending，常见原因是什么？