Home

Awesome

Jenkins Gitlab Hook Plugin

Enables Gitlab web hooks to be used to trigger SMC polling on Gitlab projects<br/> Plugin details can be found at https://wiki.jenkins-ci.org/display/JENKINS/Gitlab+Hook+Plugin

Why?

For Gitlab there is an existing solution that might work for you.<br/> You can just use the notifyCommit hook on Git plugin like this:

http://your-jenkins-server/git/notifyCommit?url=<URL of the Git repository for the Gitlab project>

But, with a large number of projects that are mostly polling (no hooks), the project might actually be built with a great delay (5 to 20 minutes).<br/> You can find more details about notifyCommit and this issue here.

That is where this plugin comes in.<br/> It gives you the option to use build_now or notify_commit hook, whichever suits your needs better.

Build now hook

Add this web hook on your Gitlab project:

http://your-jenkins-server/gitlab/build_now

Plugin will parse the Gitlab payload and extract the branch for which the commit is being pushed and changes made.<br/> It will then scan all Git projects in Jenkins and start the build for those that:

Notes:

Parameterized projects

The plugin will recognize projects that are parametrized and will use payload data to fill their values.<br/> Only String type of parameters are supported at this moment, all others are passed on with their defaults.<br/> You can reference any data from the payload, including arrays and entire sections.<br/> Here are a few examples:

NameTypeDefault ValueValue In BuildNote
TRIGGEREDBooleantruetrueNot a String parameter, using default value
TRIGGERED_BYStringN/AN/ANot found in payload or details, using default value
USER_NAMEStringDefault UserJohn SmithFrom payload, first level, not using the default value
REPOSITORY.HOMEPAGEString-http://example.com/diasporaFrom payload, nested value
COMMITS.0.MESSAGEString-Update Catalan translation to e38cb41.From payload, nested value from array
COMMITS.1String-{ "id": "da1560886d4f...", ... }From payload, entire value from array
COMMITS.1.AUTHOR.NAMEString-John Smith the SecondFrom payload, entire value from nested value in array
cOmMiTs.1.aUtHoR.nAmeString-John Smith the SecondAs above, case insensitive
FULL_BRANCH_REFERENCEString-refs/heads/masterFrom details
BRANCHString-masterFrom details

In case you define a parameter inside the branch specifier in Git configuration of the project, the plugin will replace the parameter value with the commit branch from the payload.<br/> Replacing is done by matching ${PARAMETER_KEY} in the branch specifier to the parameter list for the project.<br/>

This is useful e.g. when you want to define a single project for all the branches in the repository.<br/> Setup might look like this:

With this configuration, you have the following options:

  1. you can start a manual Jenkins build of a project, and it will ask for a branch to build
  2. for builds per commit using the Gitlab build now hook, the branch parameter will be filled in with the commit branch extracted from the payload sent from Gitlab

Advantages of this approach:

Disadvantages:

Notify commit hook

Add this web hook on your Gitlab project:

http://your-jenkins-server/gitlab/notify_commit

The procedure is the same as for the build now hook, the difference is that this hook schedules polling of the project, much like the original notifyCommit.

Additional notes

This goes for both hooks:

Delete branch commits

In case Gitlab is triggering the deletion of a branch, the plugin will skip processing entirely unless automatic branch projects creation is enabled.<br/> In that case, it will find the Jenkins project for that branch and delete it.<br/> This applies only to non master branches (master is defined in plugin configuration).<br/> Master branch project is never deleted.

Hook data related

Gitlab uses JSON POST to send the information to the defined hook.<br/> The plugin expects the request to have the appropriate structure, like this example:

{
  "before": "95790bf891e76fee5e1747ab589903a6a1f80f22",
  "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
  "ref": "refs/heads/master",
  "user_id": 4,
  "user_name": "John Smith",
  "project_id": 15,
  "repository": {
    "name": "Diaspora",
    "url": "git@example.com:diaspora.git",
    "description": "",
    "homepage": "http://example.com/diaspora"
  },
  "commits": [
    {
      "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327",
      "message": "Update Catalan translation to e38cb41.",
      "timestamp": "2011-12-12T14:27:31+02:00",
      "url": "http://example.com/diaspora/commits/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327",
      "author": {
        "name": "John Smith",
        "email": "jsmith@example.com"
      }
    },
    {
      "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
      "message": "fixed readme",
      "timestamp": "2012-01-03T23:36:29+02:00",
      "url": "http://example.com/diaspora/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
      "author": {
        "name": "John Smith the Second",
        "email": "jsmith2@example.com"
      }
    }
  ],
  "total_commits_count": 2
}

Automatic branch project creation

In case you might want to approach multiple branches by having a separate Jenkins project for each Git(lab) repository, you can turn on the appropriate plugin option.<br/> This use case workflow:

Notes:

Advantages of this approach:

Disadvantages:

For this option to become active, just turn it on in Jenkins global configuration.

Dependencies

Logging

In case you might want to inspect hook triggering (e.g. to check payload data), you can setup logging in Jenkins as usual.<br/> Just add a new logger for Class (this is because of JRuby internals).

Contributing

Testing

To help with testing, the spec/lib directory contains all the Java dependencies the plugin uses directly. The spec_helper loads them before each test run.

In case you need to add new classes, please namespace them. See existing ones for details.

Then running JRuby to execute tests, you'll need the following switches: