Gitee-Jenkins-Plugin/README_zh_CN.md

# 目录
- [简介](#简介)
  - [目前支持特性](#目前支持特性)
  - [计划中特性](#计划中特性)
- [插件安装](#插件安装)
- [插件配置](#插件配置)
  - [添加码云链接配置](#添加码云链接配置)
  - [添加码云APIV5私人令牌](#添加码云APIV5私人令牌)
  - [构建任务配置](#构建任务配置)
    - [新建构建任务](#新建构建任务)
    - [源码管理配置](#源码管理配置)
    - [触发器配置](#触发器配置)
    - [WebHook密码配置](#WebHook密码配置)
    - [构建后步骤配置](#构建后步骤配置)
      - [构建结果回评至码云](#构建结果回评至码云)
      - [构建成功自动合并PR](#构建成功自动合并PR)
    - [新建码云项目WebHook](#新建码云项目WebHook)
      - [测试推送触发构建](#测试推送触发构建)
      - [测试PR触发构建](#测试PR触发构建)
  - [使用脚本配置触发器](#使用脚本配置触发器)  
- [环境变量](#环境变量)
- [用户支持](#用户支持)
- [参与贡献](#参与贡献)
  - [打包或运行测试](#打包或运行测试)
   

# 简介
Gitee Jenkins Plugin 是码云基于 [GitLab Plugin](https://github.com/jenkinsci/gitlab-plugin) 开发的 Jenkins 插件。用于配置 Jenkins 触发器，接受码云平台发送的 WebHook 触发 Jenkins 进行自动化持续集成或持续部署，并可将构建状态反馈回码云平台。

## 目前支持特性：
- 推送代码到码云时，由配置的 WebHook 触发 Jenkins 任务构建。
- 评论提交记录触发提交记录对应版本 Jenkins 任务构建 
- 提交 Pull Request 到码云项目时，由配置的 WebHook 触发 Jenkins 任务构建，支持PR动作：新建，更新，接受，关闭，审查通过，测试通过。
- 支持 [ci-skip] 指令过滤 或者 [ci-build] 指令触发构建。
- 过滤已经构建的 Commit 版本，若是分支 Push，则相同分支Push才过滤，若是 PR，则是同一个PR才过滤。
- 按分支名过滤触发器。
- 正则表达式过滤可触发的分支。
- 设置 WebHook 验证密码。
- 构建后操作可配置 PR 触发的构建结果评论到码云对应的PR中。
- 构建后操作可配置 PR 触发的构建成功后可自动合并对应PR。
- 对于 PR 相关的所有事件，若 PR 代码冲突不可自动合并，则不触发构建；且若配置了评论到PR的功能，则评论到 PR 提示冲突。
- PR 评论可通过 WebHook 触发构建（可用于 PR 触发构建失败是便于从码云平台评论重新触发构建）
- 支持配置 PR 不要求必须测试时过滤触发构建。（可用于不需测试则不构建部署测试环境）
- 支持相同 PR 触发构建时，取消进行中的未完成构建，进行当前构建（相同 PR 构建不排队，多个不同 PR 构建仍需排队）

## 计划中特性
1. PR 审查并测试通过触发构建（可用户触发部署，且可配合自动合并 PR 的特性完善工作流。）
2. 勾选触发方式自动添加WebHook至码云。

# 插件安装
1. 在线安装
    - 前往 Manage Jenkins -> Manage Plugins -> Available
    - 右侧 Filter 输入： Gitee
    - 下方可选列表中勾选 Gitee（如列表中不存在 Gitee，则点击 Check now 更新插件列表）
    - 点击 Download now and install after restart

![输入图片说明](https://images.gitee.com/uploads/images/2018/0723/112748_b81a1ee3_58426.png "屏幕截图.png")

2. 手动安装
    - 从 [release](https://gitee.com/oschina/Gitee-Jenkins-Plugin/releases) 列表中进入最新发行版，下载对应的 XXX.hpi 文件
    - 前往 Manage Jenkins -> Manage Plugins -> Advanced
    - Upload Plugin File 中选择刚才下载的 XXX.hpi 点击 Upload
    - 后续页面中勾选 Restart Jenkins when installation is complete and no jobs are running

![输入图片说明](https://images.gitee.com/uploads/images/2018/0723/113303_2a1d0a03_58426.png "屏幕截图.png")

# 插件配置

## 添加码云链接配置
1. 前往 Jenkins -> Manage Jenkins -> Configure System -> Gitee Configuration -> Gitee connections
2. 在 ``Connection name`` 中输入 ``Gitee`` 或者你想要的名字
3. ``Gitee host URL`` 中输入码云完整 URL地址： ``https://gitee.com`` （码云私有化客户输入部署的域名）
4. ``Credentials`` 中如还未配置码云 APIV5 私人令牌，点击 ``Add`` - > ``Jenkins ``
    1. ``Domain`` 选择 ``Global credentials``
    2. ``Kind`` 选择 ``Gitee API Token``
    3. ``Scope`` 选择你需要的范围
    4. ``Gitee API Token`` 输入你的码云私人令牌，获取地址：https://gitee.com/profile/personal_access_tokens
    5. ``ID``, ``Descripiton`` 中输入你想要的 ID 和描述即可。
5. ``Credentials`` 选择配置好的 Gitee APIV5 Token
6. 点击 ``Advanced`` ，可配置是否忽略 SSL 错误（视您的Jenkins环境是否支持），并可设置链接测超时时间（视您的网络环境而定）
7. 点击 ``Test Connection`` 测试链接是否成功，如失败请检查以上 3，5，6 步骤。

配置成功后如图所示：
![码云链接配置](https://images.gitee.com/uploads/images/2018/0716/185651_68707d16_58426.png "屏幕截图.png")

### 新建构建任务
前往 Jenkins -> New Item , name 输入 'Gitee Test'，选择 ``Freestyle project`` 保存即可创建构建项目。

### 任务全局配置

任务全局配置中需要选择前一步中的码云链接。前往某个任务（如'Gitee Test'）的 Configure -> General，Gitee connection 中选择前面所配置的码云链接，如图：

![任务全局配置](https://images.gitee.com/uploads/images/2018/0716/191715_9660237b_58426.png "屏幕截图.png")


### 源码管理配置

前往某个任务（如'Gitee Test'）的 Configure -> Source Code Management 选项卡

1. 点击 *Git*
2. 输入你的仓库地址，例如 ``git@your.gitee.server:gitee_group/gitee_project.git``
    1. 点击 *Advanced* 按钮, *Name* 字段中输入 ``origin``， *Refspec* 字段输入 ``+refs/heads/*:refs/remotes/origin/* +refs/pull/*/MERGE:refs/pull/*/MERGE``
，注意新版jenkins不再接受多条同时包含 * 通配符的refs描述，如只对push触发可写前半部分，如只对PR触发可只写后半段。具体可见下图：![输入图片说明](https://images.gitee.com/uploads/images/2020/0601/220940_0ce95dd0_58426.png "屏幕截图.png")
3. 凭据Credentials 中请输入 git 仓库 https 地址对应的 用户名密码凭据，或者 ssh 对应的 ssh key 凭据，注意 Gitee API Token 凭据不可用于源码管理的凭据，只用于 gitee 插件的 API 调用凭据。
4. *Branch Specifier* 选项:
    1. 对于单仓库工作流输入: ``origin/${giteeSourceBranch}``
    2. 对于 PR 工作流输入: ``pull/${giteePullRequestIid}/MERGE``
5. *Additional Behaviours* 选项：
    1. 对于单仓库工作流，如果你希望推送的分支构建前合并默认分支（发布的分支），可以做以下操作：
        1. 点击 *Add* 下拉框
        2. 选择 *Merge before build* 
        3. 设置 *Name of repository* 为 ``origin``
        4. 设置 *Branch to merge to* 为 ``${ReleaseBranch}`` 即您要合并的默认分支（发布分支）
    2. 对于 PR 工作流，码云服务端已经将 PR 的原分支和目标分支作了预合并，您可以直接构建，如果目标分支不是默认分支（发布分支），您也可以进行上诉构建前合并。

配置如图所示：

![源码管理配置](https://images.gitee.com/uploads/images/2018/0716/191913_ef0995f4_58426.png "屏幕截图.png")

### 触发器配置

前往任务配置的触发器构建： Configure -> Build Triggers 选项卡

1. ``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 事件
2. `Build Instruction Filter` :
    - `None` : 无过滤
    - `[ci-skip] skip build` ：commit message 或者 PR 说明包含 `[ci-skip]` 时，跳过构建触发。
    - `[ci-build] trigger build` ：commit message 或者 PR 说明包含 `[ci-build]` 时，触发构建。
3. `Ignore last commit has build` 该选项可以跳过已经构建过的 Commit 版本。
4. `Cancel incomplete build on same Pull Requests` 该选项在 PR 触发构建时，会判断是否存在相同 PR 且未完成的构建，有则取消未完成构建，再进行当前构建。
5. `Ignore Pull Request conflicts` 该选项在 PR 触发构建时，会根据 PR 冲突情况选择是否进行构建。
6. `Allowed branches` 可以配置允许构建的分支，目前支持分支名和正则表达式的方式进行过滤。
7. `Secret Token for Gitee WebHook` 该选项可以配置 WebHook 的密码，该密码需要与码云 WebHook配置的密码一致方可触发构建。
8. 注意：若 PR 状态为不可自动合并，则不触发构建。
![触发器配置](https://images.gitee.com/uploads/images/2021/0107/171932_e25c8359_2102225.png "屏幕截图.png")
### 构建后步骤配置

前往任务配置的构建后配置： Configure -> Post-build Actions 选项卡

#### 构建结果回评至码云

1. 点击 `Add post-build action` 下拉框选择：`Add note with build status on Gitee pull requests`
2. `Advanced` 中可以配置：
    - Add message only for failed builds ：仅为构建失败回评到码云
    - 自定义各状态的回评内容（内容可以引用 Jenkins 的环境变量，或者自定义的环境变量）
3. 若开启该功能，还可将不可自动合并的状态回评至码云

#### 构建成功自动合并PR
点击 `Add post-build action` 下拉框选择：`Accept Gitee pull request on success`

![构建后步骤配置](https://images.gitee.com/uploads/images/2018/0716/192304_0e323bc0_58426.png "屏幕截图.png")

### 新建码云项目WebHook
进入源码管理配置中设置的码云项目中，进入 管理 -> WebHooks 

1. 添加 WebHook， URL 填写 `触发器配置：Build when a change is pushed to Gitee. Gitee webhook URL` 中所示 URL，如：: http://127.0.0.1:8080/jenkins/project/fu
2. 密码填写：触发器配置第 5 点中配置的 WebHook密码，不设密码可以不填
3. 勾选 PUSH， Pull Request

#### 测试推送触发构建
1. 码云的 WebHook 管理中选择勾选了PUSH的 WebHook 点击测试，观察 Jenkins 任务的构建状态
2. 码云项目页面编辑一个文件提交，观察 Jenkins 任务的构建状态

#### 测试PR触发构建
1. 码云的 WebHook 管理中选择勾选了 Pull Request 的 WebHook 点击测试，观察 Jenkins 任务的构建状态
2. 在码云项目中新建一个Pull Request，观察 Jenkins 任务的构建状态

## 使用脚本配置触发器
```groovy
pipeline {

    agent any

    triggers {
        gitee (
                // 推送代码
                triggerOnPush: true,
                // 评论提交记录
                triggerOnCommitComment: true,
                // 新建 Pull Requests
                triggerOnOpenPullRequest: true,
                // 更新 Pull Requests "0":None "1":Source Branch updated "2":Target Branch updated "3":Both Source and Target Branch updated
                triggerOnUpdatePullRequest: "1",
                // 接受 Pull Requests
                triggerOnAcceptedPullRequest: true,
                // 关闭 Pull Requests
                triggerOnClosedPullRequest: true,
                // 审查通过 Pull Requests	
                triggerOnApprovedPullRequest: true,
                // 测试通过 Pull Requests
                triggerOnTestedPullRequest: true,
                // 评论 Pull Requests
                triggerOnNoteRequest: true,
                // 评论内容的正则表达式
                noteRegex: "build",
                // 构建指令过滤 "NONE":无 "CI_SKIP":[ci-skip] 指令跳过构建 "CI_BUILD":[ci-build] 指令触发构建
                buildInstructionFilterType: "NONE",
                // PR 不要求必须测试时过滤构建
                ciSkipFroTestNotRequired: false,
                // 过滤已经构建的 Commit 版本
                skipLastCommitHasBeenBuild: false,
                // 取消相同 Pull Requests 未完成构建
                cancelIncompleteBuildOnSamePullRequest: false,
                // 允许触发构建的分支 "All":允许所有分支触发构建 "NameBasedFilter":根据分支名过滤 "RegexBasedFilter":根据正则表达式过滤分支
                branchFilterType: "All",
                // "NameBasedFilter" - 包括
                includeBranchesSpec: "include",
                // "NameBasedFilter" - 排除
                excludeBranchesSpec: "exclude",
                // "RegexBasedFilter" - 目标分支的正则表达式
                targetBranchRegex: "regex",
                // Gitee WebHook 密码
                secretToken: "123456"
        )
    }

    stages {
        stage('Build') {
            steps{
                echo 'Hello world!'
            }
        }
    }
}
```

# 环境变量
目前支持环境变量见以下函数，其中不同的 WebHook 触发可能导致有些变量为空，具体请安装插件 [EnvInject Plugin](https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin)，于构建中查看  Environment Variables


```java
    public Map<String, String> getBuildVariables() {
        MapWrapper<String, String> variables = new MapWrapper<>(new HashMap<String, String>());
        variables.put("giteeBranch", branch);
        variables.put("giteeSourceBranch", sourceBranch);
        variables.put("giteeActionType", actionType.name());
        variables.put("giteeUserName", userName);
        variables.put("giteeUserEmail", userEmail);
        variables.put("giteeSourceRepoHomepage", sourceRepoHomepage);
        variables.put("giteeSourceRepoName", sourceRepoName);
        variables.put("giteeSourceNamespace", sourceNamespace);
        variables.put("giteeSourceRepoURL", sourceRepoUrl);
        variables.put("giteeSourceRepoSshUrl", sourceRepoSshUrl);
        variables.put("giteeSourceRepoHttpUrl", sourceRepoHttpUrl);
        variables.put("giteePullRequestTitle", pullRequestTitle);
        variables.put("giteePullRequestDescription", pullRequestDescription);
        variables.put("giteePullRequestId", pullRequestId == null ? "" : pullRequestId.toString());
        variables.put("giteePullRequestIid", pullRequestIid == null ? "" : pullRequestIid.toString());
        variables.put("giteePullRequestTargetProjectId", pullRequestTargetProjectId == null ? "" : pullRequestTargetProjectId.toString());
        variables.put("giteePullRequestLastCommit", lastCommit);
        variables.put("giteePushCreated", created ? "true" : "false");
        variables.put("giteePushDeleted", deleted ? "true" : "false");
        variables.putIfNotNull("giteePullRequestState", pullRequestState);
        variables.putIfNotNull("giteeMergedByUser", mergedByUser);
        variables.putIfNotNull("giteePullRequestAssignee", pullRequestAssignee);
        variables.put("giteeTargetBranch", targetBranch);
        variables.put("giteeTargetRepoName", targetRepoName);
        variables.put("giteeTargetNamespace", targetNamespace);
        variables.put("giteeTargetRepoSshUrl", targetRepoSshUrl);
        variables.put("giteeTargetRepoHttpUrl", targetRepoHttpUrl);
        variables.put("giteeBefore", before);
        variables.put("giteeAfter", after);
        variables.put("giteeBeforeCommitSha", before);
        variables.put("giteeAfterCommitSha", after);
        variables.put("giteeRef", ref);
        variables.put("ref", ref);
        variables.put("beforeSha", beforeSha);
        variables.put("isTag", isTag);
        variables.put("sha", sha);
        variables.put("status", status);
        variables.put("stages", stages);
        variables.put("createdAt", createdAt);
        variables.put("finishedAt", finishedAt);
        variables.put("duration", buildDuration);
        variables.put("jsonBody", jsonBody);
        variables.put("noteBody", noteBody);
        variables.putIfNotNull("giteeTriggerPhrase", triggerPhrase);
        return variables;
    }

```

# 用户支持
如在使用过程中有任何疑问，欢迎在 [Gitee Jenkins Issue](https://gitee.com/oschina/Gitee-Jenkins-Plugin/issues) 中反馈。

反馈前可按以下步骤获取更多日志以便排查问题：

1. 前往 Jenkins -> Manage Jenkins -> System Log
2. 点击 Add new log recorder。
3. 输入 'Gitee Jenkins Plugin'。
4. 在下一页面中 Logger 点击 Add ，输入框中填写 'com.gitee.jenkins'，并在 Log level 总选择全部，保存。
5. 完成以上步骤后便可在 'Gitee Jenkins Plugin' 这个日志中查看。


# 参与贡献

欢迎提交 CI 场景特性建议或者直接提交 PR 贡献代码。


## 打包或运行测试

打包 hpi 文件在仓库目录中执行： ``mvn package``

直接运行测试执行：``mvn hpi:run``