Gitee Jenkins Plugin is a Jenkins plugin developed by Code Cloud based on GitLab Plugin. It is used to configure the Jenkins trigger, accept the WebHook sent by the code cloud platform to trigger Jenkins to perform automatic continuous integration or continuous deployment, and feedback the build status back to the code cloud platform.

Currently supported features:

• When the code is pushed to the code cloud, the configured WebHook triggers the Jenkins task build.
• The comment submission record triggers the Jenkins task construction of the corresponding version of the submission record
• When a Pull Request is submitted to the Code Cloud project, the configured WebHook triggers the Jenkins task construction, and supports PR actions: new, update, accept, close, pass review, pass test.
• support [ci-skip] command filter or [ci-build] directive triggers a build.
• Filter the Commit version that has been built. If it is a branch Push, it will be filtered only for the same branch Push, and if it is a PR, it will be filtered only for the same PR.
• Filter triggers by branch name.
• Regular expressions filter triggerable branches.
• Set the WebHook authentication password.
• Post-build operations can be configured to comment on the build results triggered by the PR to the corresponding PR of the code cloud.
• Post-build operations can be configured to automatically merge the corresponding PR after the build triggered by the PR is successful.
• For all events related to PR, if the PR code conflict cannot be automatically merged, the build will not be triggered; and if the comment to PR function is configured, the comment to PR will prompt the conflict.
• PR comments can trigger builds through WebHook (it can be used to trigger build failures from PR triggers to facilitate re-triggering builds from code cloud platform comments)
• Support for configuring PRs to filter trigger builds when testing is not required. (It can be used to build a deployment test environment without testing)
• When the same PR triggers the build, cancel the unfinished build in progress and proceed to the current build (the same PR build is not queued, and multiple different PR builds still need to be queued)

planned features

1. PR review and test trigger build (users can trigger deployment, and can improve the workflow with the feature of automatically merging PR.)
2. Check the trigger method to automatically add WebHook to Code Cloud.

1. Install online
   • Go to Manage Jenkins -> Manage Plugins -> Available
   • Filter input on the right: Gitee
   • Check Gitee in the optional list below (if Gitee does not exist in the list, click Check now to update the plugin list)
   • Click Download now and install after restart

2. manual installation
   • Enter the latest release version from the release list and download the corresponding XXX.hpi file
   • Go to Manage Jenkins -> Manage Plugins -> Advanced
   • In the Upload Plugin File, select the XXX.hpi you just downloaded and click Upload
   • Check Restart Jenkins when installation is complete and no jobs are running on the subsequent page

Add code cloud link configuration

1. Go to Jenkins -> Manage Jenkins -> Configure System -> Gitee Configuration -> Gitee connections
2. exist Connection name input in Gitee or whatever name you want
3. Gitee host URL Enter the code cloud full URL address: https://gitee.com (Code Cloud privatization customers enter the deployed domain name)
4. Credentials If you have not yet configured the code cloud APIV5 private token, click Add -> Jenkins
   1. Domain choose Global credentials
   2. Kind choose Gitee API Token
   3. Scope select the range you need
   4. Gitee API Token Enter your code cloud private token, get the address: https://gitee.com/profile/personal_access_tokens
   5. ID, Descripiton Just enter the ID and description you want.
5. Credentials Select the configured Gitee APIV5 Token
6. click Advanced you can configure whether to ignore SSL errors (depending on whether your Jenkins environment supports it), and set the link test timeout (depending on your network environment)
7. click Test Connection Test whether the link is successful, if it fails, please check the steps 3, 5, and 6 above.

After the configuration is successful, as shown in the figure:

new build task

Go to Jenkins -> New Item, name enter ‘Gitee Test’, select Freestyle project Save to create the build project.

Task global configuration

The code cloud link in the previous step needs to be selected in the task global configuration. Go to Configure -> General of a task (such as ‘Gitee Test’), select the previously configured code cloud link in the Gitee connection, as shown in the figure:

Source Control Configuration

Go to the Configure -> Source Code Management tab of a task (eg ‘Gitee Test’)

1. click Git
2. Enter your warehouse address, e.g. git@your.gitee.server:gitee_group/gitee_project.git
   1. click Advanced button, name Type in the field origin, Refspec field input +refs/heads/*:refs/remotes/origin/* +refs/pull/*/MERGE:refs/pull/*/MERGE
      , Note that the new version of jenkins no longer accepts multiple refs descriptions that contain * wildcards at the same time. For example, only the first half of the description can be written for push triggers, and only the second half can be written for PR triggers. The details can be seen in the figure below:
3. In Credentials, please enter the username and password credentials corresponding to the https address of the git warehouse, or the ssh key credentials corresponding to ssh. Note that the Gitee API Token credentials cannot be used for source code management credentials, and are only used for the API call credentials of the gitee plug-in.
4. Branch Specifier options:
   1. For a single warehouse workflow input: origin/${giteeSourceBranch}
   2. For PR workflow input: pull/${giteePullRequestIid}/MERGE
5. Additional Behaviors options:
   1. For single warehouse workflow, if you want to merge the default branch (published branch) before the pushed branch is built, you can do the following:
      1. click add drop down box
      2. choose Merge before build
      3. set up Name of repository for origin
      4. set up Branch to merge to for ${ReleaseBranch} i.e. the default branch (release branch) that you want to merge
   2. For the PR workflow, the Code Cloud server has pre-merged the original branch and the target branch of the PR, and you can directly build it. If the target branch is not the default branch (release branch), you can also perform the merge before the appeal build.

The configuration is shown in the figure:

trigger configuration

Go to the trigger build for the task configuration: Configure -> Build Triggers tab

1. Enabled Gitee triggers Check the build trigger rules you need, such as Push Event, Opened Merge Request Events, the checked event will accept the WebHook and trigger the build. Currently supported trigger events are:
   • Push Events : push code events
   • Commit Comment Events: comment submission record event
   • Opened Merge Request Events: Submit PR events
   • Updated Merge Request Events : Update PR events
   • Accepted Merge Request Events: accept/merge PR events
   • Closed Merge Request Events: Closed PR events
   • Approved Pull Requests: Approved PR events
   • Tested Pull Requests : Test passed PR event
2. Build Instruction Filter :
   • None : no filter
   • [ci-skip] skip build :commit message or PR description contains [ci-skip] skip build triggering.
   • [ci-build] trigger build :commit message or PR description contains [ci-build] the build is triggered.
3. Ignore last commit has build This option can skip the Commit version that has already been built.
4. Cancel incomplete build on same Pull Requests This option will determine whether there is an unfinished build with the same PR when a PR triggers a build, and if so, cancel the unfinished build and proceed to the current build.
5. Ignore Pull Request conflicts This option will choose whether to build according to the PR conflict when PR triggers the build.
6. Allowed branches You can configure the branches that are allowed to be built. Currently, branch names and regular expressions are supported for filtering.
7. Secret Token for Gitee WebHook This option can configure the password of the WebHook, which needs to be consistent with the password configured by the Code Cloud WebHook to trigger the build.
8. Note: If the PR status is not automatically merged, the build will not be triggered.
   

Post-build step configuration

Go to the post-build configuration of the task configuration: Configure -> Post-build Actions tab

Build results back to code cloud

1. click Add post-build action Select from the drop-down box:Add note with build status on Gitee pull requests
2. Advanced Can be configured in:
   • Add message only for failed builds : only for failed builds to comment back to Code Cloud
   • Customize the feedback content of each status (the content can refer to Jenkins environment variables, or custom environment variables)
3. If this function is enabled, the status that cannot be automatically merged can also be commented back to Code Cloud

The build is successful and the PR is automatically merged

click Add post-build action Select from the drop-down box:Accept Gitee pull request on success

Create a new code cloud project WebHook

Enter the code cloud project set in the source code management configuration, enter Management -> WebHooks

1. Add WebHook, fill in the URL 触发器配置：Build when a change is pushed to Gitee. Gitee webhook URL The URL shown in, such as: http://127.0.0.1:8080/jenkins/project/fu
2. Fill in the password: the WebHook password configured in point 5 of the trigger configuration, if you do not set a password, you can leave it blank
3. Check PUSH, Pull Request

Test push triggers build

1. In the WebHook management of Code Cloud, select the WebHook with PUSH checked and click Test to observe the construction status of the Jenkins task
2. Edit a file submission on the code cloud project page and observe the build status of the Jenkins task

Test the PR to trigger the build

1. In the WebHook management of Code Cloud, select the WebHook with Pull Request checked and click Test to observe the construction status of the Jenkins task
2. Create a new Pull Request in the code cloud project and observe the construction status of the Jenkins task

Configure triggers using scripts

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!'
            }
        }
    }
}

Currently supported environment variables are shown in the following functions. Different WebHook triggers may cause some variables to be empty. For details, please install the plug-in EnvInject Plugin and view Environment Variables in the build

    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;
    }

If you have any questions during use, welcome to feedback in Gitee Jenkins Issue.

Before feedback, you can follow the steps below to obtain more logs for troubleshooting:

1. Go to Jenkins -> Manage Jenkins -> System Log
2. Click Add new log recorder.
3. Type in ‘Gitee Jenkins Plugin’.
4. On the next page, click Add for Logger, fill in ‘com.gitee.jenkins’ in the input box, select all in Log level, and save.
5. After completing the above steps, you can check it in the log of ‘Gitee Jenkins Plugin’.

Welcome to submit CI scene feature suggestions or directly submit PR contribution code.

Package or run tests

Package the hpi file and execute it in the warehouse directory: mvn package

Run the test execution directly:mvn hpi:run