Gitee Jenkins Plugin 是Gitee基于 GitLab Plugin 开发的 Jenkins 插件。用于配置 Jenkins 触发器,接受Gitee平台发送的 WebHook 触发 Jenkins 进行自动化持续集成或持续部署,并可将构建状态反馈回Gitee平台。
简介
目前支持特性:
- 推送代码到Gitee时,由配置的 WebHook 触发 Jenkins 任务构建。
- 评论提交记录触发提交记录对应版本 Jenkins 任务构建
- 提交 Pull Request 到Gitee项目时,由配置的 WebHook 触发 Jenkins 任务构建,支持PR动作:新建,更新,接受,关闭,审查通过,测试通过。
- 支持 [ci-skip] 指令过滤 或者 [ci-build] 指令触发构建。
- 过滤已经构建的 Commit 版本,若是分支 Push,则相同分支Push才过滤,若是 PR,则是同一个PR才过滤。
- 按分支名过滤触发器。
- 正则表达式过滤可触发的分支。
- 设置 WebHook 验证密码。
- 构建后操作可配置 PR 触发的构建结果评论到Gitee对应的PR中。
- 构建后操作可配置 PR 触发的构建成功后可自动合并对应PR。
- 对于 PR 相关的所有事件,若 PR 代码冲突不可自动合并,则不触发构建;且若配置了评论到PR的功能,则评论到 PR 提示冲突。
- PR 评论可通过 WebHook 触发构建(可用于 PR 触发构建失败是便于从Gitee平台评论重新触发构建)
- 支持配置 PR 不要求必须测试时过滤触发构建。(可用于不需测试则不构建部署测试环境)
- 支持相同 PR 触发构建时,取消进行中的未完成构建,进行当前构建(相同 PR 构建不排队,多个不同 PR 构建仍需排队)
计划中特性
- PR 审查并测试通过触发构建(可用户触发部署,且可配合自动合并 PR 的特性完善工作流。)
- 勾选触发方式自动添加WebHook至Gitee。
插件安装
-
在线安装
- 前往 Manage Jenkins -> Manage Plugins -> Available
- 右侧 Filter 输入: Gitee
- 下方可选列表中勾选 Gitee(如列表中不存在 Gitee,则点击 Check now 更新插件列表)
- 点击 Download now and install after restart
-
手动安装
- 从 release 列表中进入最新发行版,下载对应的 XXX.hpi 文件
- 前往 Manage Jenkins -> Manage Plugins -> Advanced
- Upload Plugin File 中选择刚才下载的 XXX.hpi 点击 Upload
- 后续页面中勾选 Restart Jenkins when installation is complete and no jobs are running
插件配置
添加Gitee链接配置
-
前往 Jenkins -> Manage Jenkins -> Configure System -> Gitee Configuration -> Gitee connections
-
在
Connection name
中输入Gitee
或者你想要的名字 -
Gitee host URL
中输入Gitee完整 URL地址:https://gitee.com
(Gitee私有化客户输入部署的域名) -
Credential 中如还未配置Gitee APIV5 私人令牌,点击
Add
- >Jenkins
Domain
选择Global credentials
Kind
选择Gitee API Token
Scope
选择你需要的范围Gitee API Token
输入你的Gitee私人令牌,获取地址:gitee.com/profile/per…ID
,Descripiton
中输入你想要的 ID 和描述即可。
-
Credentials
选择配置好的 Gitee APIV5 Token -
点击
Advanced
,可配置是否忽略 SSL 错误(视您的Jenkins环境是否支持),并可设置链接测超时时间(视您的网络环境而定) -
点击
Test Connection
测试链接是否成功,如失败请检查以上 3,5,6 步骤。
配置成功后如图所示:
新建构建任务
前往 Jenkins -> New Item , name 输入 'Gitee Test',选择 Freestyle project
保存即可创建构建项目。
任务全局配置
任务全局配置中需要选择前一步中的Gitee链接。前往某个任务(如'Gitee Test')的 Configure -> General,Gitee connection 中选择前面所配置的Gitee链接,如图:
源码管理配置
前往某个任务(如'Gitee Test')的 Configure -> Source Code Management 选项卡
-
点击 Git
-
输入你的仓库地址,例如
git@your.gitee.server:gitee_group/gitee_project.git
- 点击 Advanced 按钮, Name 字段中输入
origin
, Refspec 字段输入+refs/heads/*:refs/remotes/origin/* +refs/pull/*/MERGE:refs/pull/*/MERGE
,注意新版jenkins不再接受多条同时包含 * 通配符的refs描述,如只对push触发可写前半部分,如只对PR触发可只写后半段。具体可见下图:
- 点击 Advanced 按钮, Name 字段中输入
-
凭据Credentials 中请输入 git 仓库 https 地址对应的 用户名密码凭据,或者 ssh 对应的 ssh key 凭据,注意 Gitee API Token 凭据不可用于源码管理的凭据,只用于 gitee 插件的 API 调用凭据。
-
Branch Specifier选项:
- 对于单仓库工作流输入:
origin/${giteeSourceBranch}
- 对于 PR 工作流输入:
pull/${giteePullRequestIid}/MERGE
- 对于单仓库工作流输入:
-
Additional Behaviours 选项:
-
对于单仓库工作流,如果你希望推送的分支构建前合并默认分支(发布的分支),可以做以下操作:
- 点击 Add 下拉框
- 选择 Merge before build
- 设置 Name of repository 为
origin
- 设置 Branch to merge to 为
${ReleaseBranch}
即您要合并的默认分支(发布分支)
-
对于 PR 工作流,Gitee服务端已经将 PR 的原分支和目标分支作了预合并,您可以直接构建,如果目标分支不是默认分支(发布分支),您也可以进行上诉构建前合并。
-
配置如图所示:
触发器配置
前往任务配置的触发器构建: Configure -> Build Triggers 选项卡
-
Enabled Gitee triggers
勾选您所需要的构建触发规则,如Push Event,Opened Merge Request Events
,勾选的事件会接受 WebHook,触发构建。目前支持触发事件有:- Push Events :推送代码事件
- Commit Comment Events :评论提交记录事件
- Opened Merge Request Events :提交 PR 事件
- Updated Merge Request Events :更新 PR 事件
- Accepted Merge Request Events :接受/合并 PR 事件
- Closed Merge Request Events :关闭 PR 事件
- Approved Pull Requests : 审查通过 PR 事件
- Tested Pull Requests :测试通过 PR 事件
-
Build Instruction Filter:
None
: 无过滤[ci-skip] skip build
:commit message 或者 PR 说明包含[ci-skip]
时,跳过构建触发。[ci-build] trigger build
:commit message 或者 PR 说明包含[ci-build]
时,触发构建。
-
Ignore last commit has build
该选项可以跳过已经构建过的 Commit 版本。 -
Cancel incomplete build on same Pull Requests
该选项在 PR 触发构建时,会判断是否存在相同 PR 且未完成的构建,有则取消未完成构建,再进行当前构建。 -
Ignore Pull Request conflicts
该选项在 PR 触发构建时,会根据 PR 冲突情况选择是否进行构建。 -
Allowed branches
可以配置允许构建的分支,目前支持分支名和正则表达式的方式进行过滤。 -
Secret Token for Gitee WebHook
该选项可以配置 WebHook 的密码,该密码需要与Gitee WebHook配置的密码一致方可触发构建。 -
注意:若 PR 状态为不可自动合并,则不触发构建。
构建后步骤配置
前往任务配置的构建后配置: Configure -> Post-build Actions 选项卡
构建结果回评至Gitee
-
点击
Add post-build action
下拉框选择:Add note with build status on Gitee pull requests
-
Advanced
中可以配置:- Add message only for failed builds :仅为构建失败回评到Gitee
- 自定义各状态的回评内容(内容可以引用 Jenkins 的环境变量,或者自定义的环境变量)
-
若开启该功能,还可将不可自动合并的状态回评至Gitee
构建成功自动合并PR
点击 Add post-build action
下拉框选择:Accept Gitee pull request on success
新建Gitee项目WebHook
进入源码管理配置中设置的Gitee项目中,进入 管理 -> WebHooks
- 添加 WebHook, URL 填写
触发器配置:Build when a change is pushed to Gitee. Gitee webhook URL
中所示 URL,如:: http://127.0.0.1:8080/jenkins/project/fu - 密码填写:触发器配置第 5 点中配置的 WebHook密码,不设密码可以不填
- 勾选 PUSH, Pull Request
测试推送触发构建
- Gitee的 WebHook 管理中选择勾选了PUSH的 WebHook 点击测试,观察 Jenkins 任务的构建状态
- Gitee项目页面编辑一个文件提交,观察 Jenkins 任务的构建状态
测试PR触发构建
- Gitee的 WebHook 管理中选择勾选了 Pull Request 的 WebHook 点击测试,观察 Jenkins 任务的构建状态
- 在Gitee项目中新建一个Pull Request,观察 Jenkins 任务的构建状态