006.Gitlab CICD流水线触发

触发方式介绍

触发方式类型

Gitlab CICD流水线的触发方式非常灵活，常见的有如下几类触发方式：

• 代码变更触发
  • push 事件触发
  • tag 推送触发

适用于常规开发流程（提交即构建）或版本发布（结合语义化版本标签）。

• 定时触发
  • 流水线计划

适用于定期执行测试套件或夜间构建/备份任务。

• 手动触发
  • 手动开始流水线
  • 手动执行单个作业

适用于高风险操作（如生产发布）或需人工审核的流程，需要准确的单个手动执行。

• API触发
  • Pipeline triggers触发
  • CI_JOB_TOKEN触发

适用于外部系统集成（如JIRA事件触发）或多项目级联部署。

• 合并请求（MR）触发
  • MR 创建/更新
  • MR 目标分支规则

适用于代码审查自动化检查或预合并验证。

• 外部事件触发
  • webhooks
  • 外部仓库同步

适用于多平台代码同步或第三方服务集成（如Docker Hub）。

总结如下：

需求场景	推荐触发方式	优势
常规开发	Push 事件	自动化程度高
生产发布	手动触发 + 保护分支	安全可控
多系统集成	API + Webhooks	跨平台兼容性好
定期维护任务	流水线计划	定时精准执行
代码审查	MR 触发	关联变更集上下文

触发方式实践

分支名触发

指定分支名触法是最简单也是最常见的触发方式，通过指定分支名的方式触发主要是通过 only 和 except 关键字实现。

• only 所有分支
  如下所示，在 only 关键字中指定 branches ，表示当前 job 会在所有分支执行。

[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:- branchesscript:- echo "Do compile work"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "all branches"
[root@gitclient myapp]# git push origin main

• only 特定分支
  如下所示，在 only 关键字中指定特定 branches ，表示当前 job 会在指定的分支执行。

[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:- main- devscript:- echo "Do compile work for main and dev"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "main and dev branches"
[root@gitclient myapp]# git push origin main

• only 反向排除
  如下所示， only 关键字和 except 配合使用，表示排除特定的 branches ，表示当前 job 会在所排除的分支之外所有分支执行。

[root@gitclient myapp]# git checkout test
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:- branchesexcept:- mainscript:- echo "Do compile work except main"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "except main branches"
[root@gitclient myapp]# git push origin test

由于排除main，因此需要在任何除main以外的分支执行。

• if条件触发
  如下所示， rules 关键字表示判断预定义变量 CI_COMMIT_BRANCH 是否等于 dev ，等于则执行 job 。

[root@gitclient myapp]# git checkout dev
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compilerules:- if: $CI_COMMIT_BRANCH == "dev"script:- echo "Do compile work if CI_COMMIT_BRANCH = dev"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work if CI_COMMIT_BRANCH = dev"
[root@gitclient myapp]# git push origin dev

如下所示，切换到 test 分支，来执行判断诶 main 分支的任务，则不会执行任何动作。

[root@gitclient myapp]# git checkout test
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compilerules:- if: $CI_COMMIT_BRANCH == "main"script:- echo "Do compile work if CI_COMMIT_BRANCH = main"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work if CI_COMMIT_BRANCH = main"
[root@gitclient myapp]# git push origin test

• 多if条件触发
  如下所示， rules 关键字添加了多个条件，从上到下任何一个判断成功，则可以执行相应的 job 。

[root@gitclient myapp]# git checkout test
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compilerules:- if: $CI_COMMIT_BRANCH == "main"- if: $CI_COMMIT_BRANCH == "test"script:- echo "Do compile work main or test"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work main or test"
[root@gitclient myapp]# git push origin test

• if排除特定分支
  如下所示， if 关键字反选，表示排除特定的 branches ，表示当前 job 会在所排除的分支之外所有分支执行。

[root@gitclient myapp]# git checkout dev
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compilerules:- if: $CI_COMMIT_BRANCH != "main"script:- echo "Do compile work except main"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work except main"
[root@gitclient myapp]# git push origin dev

• only 变量触发
  如下所示， only 关键字也可以基于预定义变量 CI_COMMIT_BRANCH 是否等于 dev ，来执行有关 job 。

[root@gitclient myapp]# git checkout main
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:variables:- $CI_COMMIT_BRANCH == "main"script:- echo "Do compile work only main"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work only main"
[root@gitclient myapp]# git push origin main

• only 变量排除触发
  如下所示， only 关键字也可以基于预定义变量 CI_COMMIT_BRANCH 进行反向排除，来执行有关 job 。

[root@gitclient myapp]# git checkout dev
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:variables:- $CI_COMMIT_BRANCH != "main"script:- echo "Do compile work only main"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work only except main"
[root@gitclient myapp]# git push origin dev

通常 only 和 except 更清晰明了，对于复杂的判断场景可使用 if 进行定义。

MR触发

通过 MergeRequest 触发流水想的 job 的事件是 merge_request 。

• only+refs方式
  可以通过 only 关键字，即 only.refs 指定 merge_request 实现。

[root@gitclient myapp]# git checkout main
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:refs:- merge_requestsscript:- echo "Do compile work for main use merge_requests"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work for main use merge_requests"
[root@gitclient myapp]# git push origin main

在使用 only 和 except 关键字的时候，也可以省略 refs 字段，即如上等效于如下：

stages:- compilecompile:stage: compileonly:- merge_requestsscript:- echo "Do compile merge_requests for main not use refs "tags:- study-runner

• only+预变量方式
  可以通过 only 关键字，结合预变量指定 merge_request 实现。

stages:- compilecompile:stage: compileonly:variables:- $CI_PIPELINE_SOURCE == "merge_requests_event"script:- echo "Do compile merge_requests for main use only var"tags:- study-runner

• rules方式
  可以通过 rules 关键字，结合预变量，指定 merge_request 实现。

stages:- compilecompile:stage: compilerules:- if: $CI_PIPELINE_SOURCE == "merge_requests_event"script:- echo "Do compile merge_requests for main use rules"tags:- study-runner

修改任何基于 main 所创建的分支里的任意文件，如 test 里的 README.md ，用于后续合入测试。

[root@gitclient myapp]# git checkout test
Switched to branch 'test'
[root@gitclient myapp]# vi README.md
# myapp## Test
Test my first mr file#……[root@gitclient myapp]# git add .
[root@gitclient myapp]# git commit -m "modity file to mr"
[root@gitclient myapp]# git push origin test

进入 myapp 项目，代码 ——> 合并请求，创建新的合并请求，将已经修改过的 test 支线合入 main。

选择源分支和目标分支。

新建合并请求。

确认合并情况。

当前流水线是判断有合入请求的时候，就执行相应的 job ，因此在 test 如何 main后，会执行作业。

总结：实现MR的触发方式多种，对于简单场景，建议使用 only 方式，需要和其他条件结合使用的复杂场景，可使用 rules 方式。

tag触发

通常对于研发流水线而言，当一个里程碑或者周期性完成的时候，会通过 tag 的方式对代码做备份快照。
打了 tag 后，期望可以触发流水线。

• 创建流水线

可以通过 only 关键字，指定特定的 tag ，如下所示：

[root@gitclient myapp]# git checkout main[root@gitclient myapp]# git rm .gitlab-ci.yml
[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compileonly:- tagsscript:- echo "Do compile work use only tags"- echo "Test tags"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work use only tags"[root@gitclient myapp]# git push origin main

• 测试打tag
  图形界面进行myapp项目，标签 ——> 新建标签 。
  

创建一个测试的 tag 。

然后观察流水线是否自动触发。

手动人为触发

通常对于研发流水线，在一些特定或者非常重要环境，比如更新数据库、升级生产环境等，可能需要人工审核手动触发。

手动触发需要结合 when 关键字，设置为 manual 来实现。
手动触发通常需要和其他触发条件配合使用。

• 创建流水线
  如下所示，通过 only 关键字控制当前 job 在 main 分支和打 tag 的时候触发，同时又通过 when 关键字指定 manual 设置为手动触发。
  此时 job 的执行方式是首先需要满足 only 设置的触发条件，即只有在 main 分支或者打 tag 的时候，流水线才会出现在 gitlab 界面上，然后设置为手动单击触发。

[root@gitclient myapp]# git rm .gitlab-ci.yml
[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compilewhen: manualonly:- main- tagsscript:- echo "Do compile work use only tags"- echo "Test tags"- echo "Test manual"tags:- study-runner[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work test tag & manual"[root@gitclient myapp]# git push origin main

提交后需要手动执行。

手动执行后观察执行结果。

定时任务触发

对于一些周期性的操作，比如数据采集、数据分析等，可以设置定时任务执行。

• 创建流水线
  有如下多种方式创建相同效果的流水，任选一种即可。

[root@gitclient myapp]# git rm .gitlab-ci.yml
[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile:stage: compilewhen: manualonly:- schedulesscript:- echo "Do compile work use only schedules"tags:- study-runner

如上流水线采用 only ，only 中可以省略 refs ，因此如上流水线等价于如下：

stages:- compilecompile:stage: compilewhen: manualonly:refs:- schedulesscript:- echo "Do compile work use only schedules refs"tags:- study-runner

也可以使用如下 rules 实现：

stages:- compilecompile:stage: compilewhen: manualrules:refs:- if: $CI_PIPELIN_SOURCE == "schedules"script:- echo "Do compile work use rules schedules"tags:- study-runner

同样 only 也可以使用变量实现：

stages:- compilecompile:stage: compilewhen: manualonly:variables:- $CI_PIPELIN_SOURCE == "schedules"script:- echo "Do compile work use only var schedules"tags:- study-runner

• 提交流水线

[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile use only schedules"
[root@gitclient myapp]# git push origin main

如上提交流水线后，由于是基于 only schedules 才会触发流水线作业，因此可在 gitlab webui 创建一个 schedules （流水线计划），用来观察流水线是否自动触发。

• 创建schedules
  图形界面进行myapp项目，构建 ——> 流水线计划 ——> 创建新的流水线计划 。

该流水线计划是采用 cron 语法，即等价于 Linux 中的定时语法。

创建完即可在流水线计划中查看到已创建的记录。

可以查看下一次运行的具体时间，确认是否符合预期。

提示：对于 cron 可以直接通过在线工具进行生成所需计划任务： crontab表达生成器

等定义的时间到，流水作业会自动运行。

指定文件变更触发

可以配置通过 changes 关键字，实现检测指定文件是否变更而触发流水线。
主要适应的场景如下：某个代码仓库中，有前端项目目录，也有后端项目目录，当后端项目目录中的代码发生了安恒，只需要将后端应用对应的流水线触发即可，前端项目的流水线不需要执行，反之亦然。

• 创建流水线
  如下所示，编译前后端的 Job 拆分为独立的两个，分别进行检测。
  如果 Web 目录下的文件发生了变化，则编译前端项目；
  如果 back 目录下的文件发生了变化，则编译后端项目。

[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile_back:stage: compileonly:changes:- back/**/*script:- echo "Do compile back work"tags:- study-runnercompile_web:stage: compileonly:changes:- web/**/*script:- echo "Do compile web work"tags:- study-runner

• 提交流水线

[root@gitclient myapp]# mkdir web back
[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile test changes"
[root@gitclient myapp]# git push origin main

如上提交流水线后，由于是基于 only changes 才会触发流水线作业，因此当对应目录里文件发生改变的时候会自动触发对应的流水线。

• 模拟文件改变
  测试文件改变后的流水线执行情况。

[root@gitclient myapp]# echo 'Test changes web file' > web/test.txt
[root@gitclient myapp]# git add .
[root@gitclient myapp]# git commit -m "Do compile web changes"[root@gitclient myapp]# git push origin main

观察流水线执行情况。

结合分支及文件变更触发

当指定文件变更的同时还可以结合对应的分支，从而实现特定的分支下的某个文件变更来触发流水线。

• 创建流水线

[root@gitclient myapp]# git checkout dev
[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile_back:stage: compileonly:refs:- main- devchanges:- back/**/*script:- echo "Do compile main or dev back work"tags:- study-runnercompile_web:stage: compileonly:refs:- main- devchanges:- web/**/*script:- echo "Do compile main or dev web work"tags:- study-runner

如上流水线也可以使用 rules 关键字实现，如上流水线等价于：

stages:- compilecompile_back:stage: compilerules:- if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "dev"changes:- back/**/*script:- echo "Do compile main or dev back work use rules"tags:- study-runnercompile_web:stage: compilerules:- if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "dev"changes:- web/**/*script:- echo "Do compile main or dev web work use rules"tags:- study-runner

• 提交流水线

[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile test changes for main or dev"
[root@gitclient myapp]# git push origin dev

如上提交流水线后，由于是基于 only changes 才会触发流水线作业，因此当对应分支的目录里的文件发生改变的时候会自动触发对应的流水线。

• 模拟文件改变
  测试文件改变后的流水线执行情况。

[root@gitclient myapp]# mkdir web back
[root@gitclient myapp]# echo 'Test changes back file' > web/test.txt
[root@gitclient myapp]# git add .
[root@gitclient myapp]# git commit -m "Do compile back changes"[root@gitclient myapp]# git push origin dev

观察流水线执行情况。

总结：对于目录中的文件是否发生变化从而触发流水线，对于一个项目存在多个微服务，且在同一个代码仓的时候能灵活满足场景的需求。

正则语法触发

可以通过预定义变量结合正则表达式来触发流水线，对于一些特定场景比较实用。

• 创建流水线
  如下所示表示存在多个开发小组和前端小组分支，当 commit 的请求来自任何 dev 开发小组，则执行对应的流水线。
  正则表达式

[root@gitclient myapp]# git checkout -b firstdev
[root@gitclient myapp]# git checkout -b secdev[root@gitclient myapp]# git rm .gitlab-ci.yml[root@gitclient myapp]# vim .gitlab-ci.yml
stages:- compilecompile_back:stage: compileonly:variables:- $CI_COMMIT_BRANCH =~ /.*dev$/script:- echo "Do compile work use var regular"tags:- study-runner

如上流水线也可以使用 rules 关键字实现，如上流水线等价于：

stages:- compilecompile_back:stage: compilerules:- if: $CI_COMMIT_BRANCH =~ /.*dev$/script:- echo "Do compile work use rules regular"tags:- study-runner

• 提交流水线

[root@gitclient myapp]# git add .gitlab-ci.yml
[root@gitclient myapp]# git commit -m "Do compile work use var regular"
[root@gitclient myapp]# git push origin secdev

如上提交流水线后，由于是基于 secdev 分支提交的，因此会自动触发流水线作业，观察流水线执行情况。

总结：对于目录中的文件是否发生变化从而触发流水线，对于一个项目存在多个微服务，且在同一个代码仓的时候能灵活满足场景的需求。