gitlab-ci-local：一条命令在本地跑通 GitLab CI，改完配置再也不用推送等结果

gitlab-ci-local：一条命令在本地跑通 GitLab CI，改完配置再也不用推送等结果

【免费下载链接】gitlab-ci-localTired of pushing to test your .gitlab-ci.yml?项目地址: https://gitcode.com/GitHub_Trending/gi/gitlab-ci-local

开场：一个扎心的开发日常

你改了一行.gitlab-ci.yml的拼写，为了验证它能不能用，不得不git commit、git push，然后盯着远程流水线转上几分钟——结果红了，错误信息只有一行，而修复又得再推一次。来回三五趟之后，一个本可以十分钟解决的小改动耗掉了大半天。这类"改配置必须推送验证"的循环，正是 gitlab-ci-local 想要砍掉的东西：它把整条 GitLab 流水线搬到你的终端里跑，配置对不对、脚本能不能过，几秒到几分钟内就有答案。

项目定位：一句话说清它是谁

gitlab-ci-local 是一个命令行工具，面向使用 GitLab CI/CD 的开发者，让你在本地按 shell 或 docker 两种执行器模拟完整的 GitLab Runner 行为，用来测试和调试.gitlab-ci.yml，而不必推送到远程仓库。

快速上手：最短路径跑起来

任选一种方式装好二进制，然后在任意 Git 仓库根目录执行即可：

# Debian/Ubuntu sudo apt-get install gitlab-ci-local # 或 npm 全局安装 npm install -g gitlab-ci-local # macOS brew install gitlab-ci-local

# 在仓库根目录直接运行整条流水线 gitlab-ci-local # 加个别名，以后敲 gcl 就行 echo "alias gcl='gitlab-ci-local'" >> ~/.bashrc

注意：它只同步 git 已跟踪的文件，所以新加的文件记得先git add，否则作业里可能看不到它。

核心用法：跟着真实任务走

任务一：先"看一眼"流水线会跑哪些作业

推送之前先用列表模式预检，--list会把参与本次运行的作业以表格形式打印出来，并自动过滤掉when: never的作业：

gitlab-ci-local --list

输出包含作业名、描述、stage、when、allow_failure 和 needs 依赖，一眼就能确认"这次到底会执行哪些东西"。想连被规则隐式排除的作业也列出来，可换成--list-all；需要脚本化处理时，--list-csv直接给出 CSV 格式。

任务二：只跑其中一个作业

调试某个具体脚本时，把作业名直接跟在命令后面即可，无需执行整条流水线：

# 只运行 npm-install 这一个 job gitlab-ci-local npm-install

这是日常开发中最常用的一种姿势：改动集中在哪个作业，就单独跑哪个。

任务三：管理敏感变量，不进代码库也不进 git

把密码、token 之类的值放进变量文件，工具默认读取仓库根目录下的.gitlab-ci-local-variables.yml：

# .gitlab-ci-local-variables.yml AUTHORIZATION_PASSWORD: djwqiod910321 DOCKER_LOGIN_PASSWORD: dij3213n123n12in3 KNOWN_HOSTS: '~/.ssh/known_hosts' # 值是文件路径时，会按 File 类型变量注入

该文件务必加入.gitignore。如果你有多个仓库共用同一套凭据，还可以在全局文件$HOME/.gitlab-ci-local/variables.yml里按 git remote 地址、group 或 global 三个层级分发变量，匹配上对应远程仓库的作业才会注入。

任务四：用装饰器给作业"加料"

gitlab-ci-local 支持在 YAML 注释里写特殊装饰器，这些注释不影响 GitLab 本身，只在本地生效。比如给作业加描述、加交互模式：

# @Description Install npm packages npm-install: image: node script: - npm install --no-audit # @Interactive interactive-shell: rules: - if: $GITLAB_CI == 'false' when: manual script: - docker run -it debian bash

@Description会在--list输出里显示描述文本；@Interactive让作业以交互方式运行，配合when: manual触发后可以在本地直接起一个带 shell 的容器排查问题。此外还有@InjectSSHAgent（自动加载 SSH agent）和@NoArtifactsToSource（阻止制品回拷到源码目录）。

高阶技巧：让效率再翻一倍

• 默认参数固化成文件：所有 CLI 选项都可以通过环境变量（GCL_NEEDS=true、GCL_TIMESTAMPS=true这类）或.gitlab-ci-local-env/$HOME/.gitlab-ci-local/.env文件设置默认值，省得每次敲长串参数。
• include 缓存与强制刷新：外部 include 默认只拉取一次并缓存，保证离线也能跑；确认要拿最新版时加--fetch-includes。
• shell 作业的隔离模式：shell 执行器默认把制品直接写回当前目录，--shell-isolation可以模拟更接近远程 Runner 的隔离行为，验证 artifact 传递是否真的依赖正确。
• 组件 inputs 的本地覆盖：使用 CI/CD 组件时，可用--inputs-file（默认.gitlab-ci-local-inputs.yml）提供输入值；遇到老组件类型声明与实际值不兼容导致校验失败时，--skip-input-validation可以放宽类型检查（必填项与插值键仍会校验）。
• Tab 补全一键开启：gitlab-ci-local --completion >> ~/.bashrc，作业名、参数补全都就位。

原理剖析：它是怎么做到的

项目用 TypeScript 编写，核心逻辑集中在 src/ 目录，模块划分相当清晰：

• src/parser.ts 负责解析.gitlab-ci.yml，包括extends、include、rules 展开等，产出一份"扁平化"的流水线结构；
• src/job.ts 封装单个作业的生命周期，决定用 shell 还是 docker 执行器、注入哪些环境变量、如何收集 artifacts；
• src/executor.ts 按 stage 和needs关系编排作业的执行顺序与并发；
• src/variables-from-files.ts 解析项目级、用户级变量文件，并按 remote 匹配分发；
• src/validator.ts 配合从 GitLab 上游同步来的schema.json做配置校验，保证你写的 YAML 在真实 GitLab 上也是合法的。

测试组织在 tests/test-cases/ 下，每个用例一个独立目录，覆盖了缓存、artifacts、needs、parallel matrix、include 等上百种场景，这也是它能持续跟上 GitLab 新特性的底气所在。

避坑手册：这些坑先替你踩了

怎么选：它适合你吗

适合你，如果你：日常维护.gitlab-ci.yml，频繁调整 stages、rules、needs；需要在推送前验证 artifacts、cache、include 这类"只有真跑一遍才知道对错"的机制；或者团队想统一用同一份 CI 配置做本地预演，替代零散的 shell 脚本和 Makefile。

不适合你，如果你：不用 GitLab CI（它并不通用，行为是对齐 GitLab Runner 语义的）；或者需要完全复刻生产 Runner 的环境差异——它尽力模拟，但本地机器与 Runner 宿主机终究不同，最终结果仍要以远程流水线为准。

相比"推到远程看结果"这一传统路径，它的取舍很明确：用本地的一次执行，换掉远程多次失败重试等待的时间。

写在最后

把gitlab-ci-local装好、别名叫成gcl，然后在你下一个要改 CI 配置的午后直接跑gcl --list试试——你会发现"推送才能验证"这件事，从此可以成为历史。

【免费下载链接】gitlab-ci-localTired of pushing to test your .gitlab-ci.yml?项目地址: https://gitcode.com/GitHub_Trending/gi/gitlab-ci-local