GitLab CI/CD 官方文档（国内镜像）

开发者和运维团队用它把代码提交到生产部署的全流程自动化——在项目根目录放一个.gitlab-ci.yml文件，就能定义构建、测试、部署各阶段的任务，由Runner代理执行，并通过变量、组件、表达式实现灵活配置。

核心配置：.gitlab-ci.yml 与流水线结构

所有CI/CD逻辑都写在一个YAML文件里，文件名必须为.gitlab-ci.yml（区分大小写），但可配置其他文件名。文件定义stages（阶段，如build、test、deploy）和jobs（每个阶段内的具体任务），流水线由这些阶段和任务按顺序组成。触发方式包括代码推送、合并请求、定时计划或手动点击“运行流水线”按钮。

• 阶段顺序：stages决定执行次序，典型顺序为buildtestdeploy
• 任务隔离：每个job在独立容器或虚拟机中运行，Runner加载指定镜像后克隆项目并执行脚本
• 触发事件：git push、Web API、UI按钮、MR创建/更新、合并列车、定时计划、上游项目订阅、Auto DevOps、外部PR集成

Runner：作业执行代理

Runner是运行作业的代理，可部署在物理机或虚拟机上。GitLab.com已提供Linux、Windows、macOS的共享Runner，Self-Managed实例需自行注册或创建Runner。Runner在运行时加载指定的容器镜像，克隆项目代码，然后在本地或容器内执行job脚本。

• 共享Runner：GitLab.com用户开箱即用，无需自建
• 自建Runner：支持注册到项目、组或实例，也可在本地机器上创建
• 镜像指定：在.gitlab-ci.yml中通过image关键字指定作业运行的容器镜像

变量、表达式与组件：动态配置与复用

CI/CD变量是键值对，用于存储密码、API密钥等敏感信息或配置参数，可在.gitlab-ci.yml中硬编码、在项目设置中配置或动态生成。变量类型包括自定义变量和预定义变量（自动提供作业、流水线、环境信息），并支持保护变量（仅限受保护分支/标签）和掩码变量（隐藏日志输出）。表达式使用$[[ ]]语法，在流水线创建时验证，支持inputs上下文（接收来自父文件或手动运行的参数）和matrix上下文（在矩阵作业间创建1:1映射）。CI/CD组件是可复用的流水线配置单元，通过include:component引入，可发布到CI/CD目录供多项目共享。

• 变量作用域：项目级、组级、实例级，优先级从低到高
• 表达式验证：在流水线编辑器中可提前验证表达式语法，避免提交后失败
• 组件模板：GitLab提供常见任务和集成的CI/CD组件模板
• 组件复用：减少重复配置，提升跨项目一致性

安全与开发指南（来自中文文档）

极狐GitLab中文文档提供了CI/CD开发安全指南，强调将流水线视为写操作、远程执行隔离、限制操作范围等原则。开发者在设计触发流水线的功能时，需明确执行者身份，避免创建流水线的用户与变更作者不一致。作业执行用户可能与流水线用户不同（如手动作业、重试作业），需考虑CI_JOB_TOKEN的权限范围。

• 流水线写操作：触发流水线会改变系统状态（部署、测试、配置），需谨慎授权
• 显式触发：用户应在操作前明确知晓将启动流水线或作业
• 范围限制：新端点与CI_JOB_TOKEN配合时，优先限制到同一作业或流水线，避免跨项目暴露
• 审计日志：为触发流水线的事件记录详细日志，包括流水线用户、操作者和事件详情

常见问题

Q1：GitLab CI/CD 的 .gitlab-ci.yml 文件必须放在项目根目录吗？

A1：默认必须放在项目根目录，文件名区分大小写（.gitlab-ci.yml），但可以通过配置指定其他路径或文件名。

Q2：GitLab CI/CD 的变量如何保护敏感信息不被泄露？

A2：支持两种安全设置：保护变量（仅对受保护分支或标签上的作业可见）和掩码变量（在作业日志中隐藏变量值，防止密码或API密钥暴露）。

Q3：极狐GitLab 中文文档与 GitLab 官方文档内容一致吗？

A3：极狐GitLab（docs.gitlab.cn）提供完整的中文翻译文档，覆盖CI/CD、安全合规、安装管理等模块，内容与官方文档同步，并额外包含针对中国用户的本地化指南（如CI/CD开发安全指南）。

更多同类工具与网站,可在构建工具分类继续挑选。

信息核实于 2026年7月,具体以官网为准。