How to Filter Branches in Jenkins Using Generic Webhook Trigger with Gitee

Knowledge Background

When using Gitee Webhooks for continuous integration, each code push triggers a POST request to the Jenkins server. The Generic Webhook Trigger plugin receives this request and parses its parameters. The push data from Gitee includes a JSON field ref that indicates the branch, e.g. "ref": "refs/heads/master".

The Gitee Webhooks documentation provides the full data format.

Experiment to Identify Branch Flag

1. Preparation: In Gitee project settings under Webhooks, set the POST URL to http://xuliugen.vicp.io:8030/api/jenkins. This address is exposed via a port‑forwarding service for local debugging.

2. A simple web service (SSM project) is started on port 8030. The service defines a GitOSPostBean generated from the Gitee push JSON (using the IDEA plugin GsonFormat).

3. The test project jenkins-test has several branches:

4. Modify the develop branch (full name refs/remotes/origin/develop) and push. The received ref value is refs/heads/develop.

5. Modify the feature branch 20170727-webhooks (full name refs/heads/feature/liugen.xu/20170727-webhooks) and push. The ref value becomes refs/heads/feature/liugen.xu/20170727-webhooks.

These experiments confirm that the ref field reliably distinguishes branches.

Configuring Jenkins

The plugin configuration looks like the following screenshot:

The Generic Webhook Trigger consists of Post content parameters , Header parameters , Request parameters , and an Optional filter . The optional filter is the only component that can restrict builds to specific branches.

Example of adding a parameter in the post content:

If you want "param1" in post content {"param1":"value1"} posted to http://JENKINS_URL/generic-webhook-trigger/invoke, you need to add "$.param1" here.

The optional filter uses an expression that matches a value from the POST data. For branch filtering, set the variable name to ref and the expression to $.ref. Then provide a regular expression in the filter, e.g. ^(refs/heads/develop)$ to match only the develop branch.

Testing the regular expression shows a successful match for refs/heads/develop:

To match other branches, adjust the regex accordingly, for example:

1. Match refs/heads/master : ^(refs/heads/master)$ 2. Match refs/heads/feature/liugen.xu/20170727-webhooks : ^(refs/heads/feature/liugen\.xu/20170727-webhooks)$

Test results show that when the branch matches, Jenkins logs a successful build:

[Handling POST /generic-webhook-trigger/invoke from 61.160.47.7 : http-apr-8020-exec-7] org.jenkinsci.plugins.gwt.GenericWebHookRequestReceiver.doInvoke Triggering jenkins-test
[Executor #1 for master : executing jenkins-test #23] hudson.model.Run.execute jenkins-test #23 main build action completed: SUCCESS

When the branch does not match, the filter prevents the build:

[Handling POST /generic-webhook-trigger/invoke from 61.160.47.7 : http-apr-8020-exec-6] org.jenkinsci.plugins.gwt.GenericTrigger.isMatching Not triggering "^(refs/heads/develop)$" not matching "refs/heads/feature/liugen.xu/20170727-webhooks".

Summary

The experiment demonstrates how to determine the branch flag from Gitee push data and configure the Generic Webhook Trigger plugin to filter builds by branch using an optional regular‑expression filter. Although the plugin is less common than GitHub integrations, this step‑by‑step guide should help anyone needing branch‑specific CI triggers with Gitee.