gitlab-ci

用途

GitLab CI/CD 用于自动化软件交付流水线，把构建、测试、部署等环节串联起来。当需要在 GitLab 中搭建 CI/CD 流水线、配置 GitLab Runner（共享或自托管）、创建多阶段部署流水线、实现 GitLab Auto DevOps、管理 CI/CD 变量与密钥时，可以使用该技能。

前置条件

GitLab 仓库（gitlab.com 或自托管）
对 YAML 的基本理解
若使用自托管 Runner：Linux 服务器或 Kubernetes 集群

主要能力

流水线配置

在仓库根目录创建 .gitlab-ci.yml，定义 stages（如 build、test、deploy）、variables 以及各阶段作业。示例中 build 作业使用 node 镜像执行 npm ci 与 npm run build，并通过 artifacts 输出 dist/，设置 expire_in 为 1 hour；test 作业执行 npm test 并配置 coverage 正则；deploy 作业通过 environment 指定生产环境名称与 URL，并用 only 限定 main 分支。

作业配置

基于 rules 的执行控制：可按分支、流水线来源等条件设置 when（manual、never、on_success）。
并行作业：通过 parallel 数值拆分测试分片，结合 CI_NODE_INDEX 与 CI_NODE_TOTAL 使用。
矩阵构建：通过 parallel.matrix 组合不同 NODE_VERSION 与 OS 变量生成多个作业。

缓存与制品

缓存：通过 cache.key（可基于 package-lock.json 等文件）与 paths 缓存 node_modules/ 等目录，policy 可设为 pull-push 或 pull。
制品：通过 artifacts.paths 保存 dist/、coverage/ 等，可配置 reports（junit、coverage_report 的 cobertura 格式）、expire_in 与 when。

环境与部署

可定义 deploy_staging 作业，设置 environment 的 name、url 与 on_stop，并配套 stop_staging 作业（action: stop，when: manual）实现环境停止。

Docker 构建

使用 docker:24 镜像与 docker:24-dind 服务，设置 DOCKER_TLS_CERTDIR，登录 CI 镜像仓库后构建并推送镜像（使用 CI_REGISTRY_USER、CI_REGISTRY_PASSWORD、CI_REGISTRY、CI_REGISTRY_IMAGE、CI_COMMIT_SHA 等变量）。

GitLab Runner

安装与注册：资料给出 gitlab-runner --version 检查版本，以及 gitlab-runner register 命令示例（指定 url、registration-token、executor docker、docker-image alpine:latest）。资料说明 Runner 需从组织批准的签名包安装，本指南不获取或执行远程引导脚本。
Runner 配置：/etc/gitlab-runner/config.toml 中可配置 name、url、token、executor，以及 runners.docker 下的 image、privileged、volumes。
Runner 标签：作业可通过 tags 指定所需 Runner 标签（如 docker、linux）。

CI/CD 变量

在 Settings > CI/CD > Variables 中定义受保护、掩码的变量（示例：AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）。作业中可直接引用变量，也可在作业内定义 variables（如 AWS_DEFAULT_REGION）。

Include 与 Extend

include 可引入模板（如 Security/SAST.gitlab-ci.yml）、其他项目的文件或本地文件。
extends 可复用基础作业（如 .base_job 定义 image 与 before_script），build 与 test 作业继承后各自定义 script。

多项目流水线

通过 trigger 配置下游项目（project、branch、strategy: depend）触发多项目流水线。

使用方式

在仓库根目录编写 .gitlab-ci.yml，按阶段组织作业；根据需要在 GitLab 界面配置变量与 Runner；通过 include 复用模板、通过 extends 复用作业定义；使用 rules 控制执行条件，使用 cache 与 artifacts 在作业间传递数据。

适用场景

在 GitLab 中搭建从构建到部署的自动化流水线
配置共享或自托管 Runner
多阶段部署与环境管理
Docker 镜像构建与推送
多项目流水线编排

常见问题

流水线卡住：作业一直处于 pending，检查 Runner 可用性与标签匹配。
Docker-in-Docker 失败：无法连接 Docker 守护进程，使用 docker:dind 服务并正确配置 TLS。
缓存不生效：作业间缓存未命中，检查缓存 key 并确保 Runner 共享分布式缓存。

最佳实践

复杂条件使用 rules 而非 only/except
利用 GitLab 内置安全扫描模板
使用作业依赖优化流水线速度
为合并请求实现 review apps
积极缓存依赖
使用制品在阶段间传递数据

限制

指南会在真实环境执行：应用任何变更前需确认目标、影响范围与回滚方案。
未经明确批准，绝不部署到生产环境。
本文档为纯文档导入：上游脚本与模板未随附打包。

技能介绍

用途