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而不必推送到远程仓库。维度说明项目定位本地运行 GitLab CI 流水线的 CLI 工具解决的核心问题改 CI 配置只能推送远程验证、反馈慢执行方式shell 执行器 / docker 执行器双模式适用平台Linux、macOS、WindowsGit Bash安装方式apt 仓库、npm、Bun、Homebrew、AUR 均可快速上手最短路径跑起来任选一种方式装好二进制然后在任意 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 gclgitlab-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 bashDescription会在--list输出里显示描述文本Interactive让作业以交互方式运行配合when: manual触发后可以在本地直接起一个带 shell 的容器排查问题。此外还有InjectSSHAgent自动加载 SSH agent和NoArtifactsToSource阻止制品回拷到源码目录。高阶技巧让效率再翻一倍默认参数固化成文件所有 CLI 选项都可以通过环境变量GCL_NEEDStrue、GCL_TIMESTAMPStrue这类或.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 执行器、注入哪些环境变量、如何收集 artifactssrc/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 新特性的底气所在。避坑手册这些坑先替你踩了现象原因解决作业里看不到新建的文件只有 git 已跟踪的文件会同步进隔离作业先git add相关文件变量在作业中取不到变量文件名或层级没配对默认读.gitlab-ci-local-variables.yml用--variables-file显式指定或检查 home 级变量文件的 remote 匹配规则外部 include 内容没更新远程 include 默认只拉取一次并缓存加--fetch-includes强制重新获取自托管 GitLab 地址里带自定义端口端口类变量未按实例配置在变量文件里手动设置CI_SERVER_PORT、CI_SERVER_SHELL_SSH_PORT本地跑通的制品行为与远程不一致shell 执行器会把制品直接拷回源码目录加--shell-isolation模拟隔离或用NoArtifactsToSource精确控制怎么选它适合你吗适合你如果你日常维护.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考