Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Gitlab Hook on the plugin site for more information.

The current version of this plugin may not be safe to use. Please review the following warnings before use:

Enables Gitlab web hooks to be used to trigger SMC polling on Gitlab projects


For Gitlab there is an existing solution that might work for you.
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).
You can find more details about notifyCommit and this issue here.

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

Version history

Open issues

T Key Summary Assignee Reporter P Status Resolution Created Updated Due

Version 1.4.2 (Apr 2016)

  • Full support recent GitLab 8.x releases
  • Support for GitLab 8.1 commit statuses
  • JENKINS-33836, remove merge request projects even when merged branches triggering is disabled
  • JENKINS-33252, skip reporting if gitlab url/token not configured
  • JENKINS-29317, implemented endpoint for triggering a specific jenkins project
  • JENKINS-30322, report on job log about communications through gitlab API
  • JENKINS-28808, fixed Multiple SCMs projects
  • Avoid tag building projects to be elected as candidates to automatically create projects
  • Improved acceptance tests & documentation

Version (Jan 2016)

  • JENKINS-28327, uncaptured exception on malformed congiguration file
  • JENKINS-28452, configurable triggering for projects with pre-build merges
  • Fixed parameter serialization for tag builds

Version 1.4.0 (May 2015)

Version 1.3.1 (Feb 27 2015)

  • JENKINS-27101, exception happens when creating a project from a template
  • Issue #56, elevated privileges required for automatic project creation

Version 1.3.0 (Feb 19 2015)

  • Template based automatic project creation
  • Improved branch matching. Mainly allow exact matches for */master and allow branch specifications starting with refs/

Version 1.2.1 (Feb 3 2015)

  • Issue #3 allowing also choice parameter type for branch name parameter

Version 1.2.0 (Jan 19 2015)

  • Issue #44 global configuration for automatic project per branch creation
  • Issue #50 trigger the build only for multi configuration project, not it's axis
  • Issue #31 payload data is auto-filled to job parameters
  • Issue #41 supporting refspec matching (if refspec present in job configuration)
  • Issue #39 multiple smc's support
  • Issue #42 git 2 support
  • Issue #43 better error handling, exceptions converted to java RuntimeException
  • #JENKINS-24232 fix for branch specifier that is not of String type, now just skipping such projects instead of raising exception
  • Issue #45 fix for getting branch name from payload, did not work correctly for tags
  • fix for invalid or empty payload, returns the actual payload sent and a more meaningful description
  • catching invalid route, displaying known routes and link to wiki
  • improved logging for request details, payload, matching projects
  • displaying stack trace on exception, nicely formatted for api response or in log

Version 1.1.0 (Jul 13 2014)

  • Issue #30 supporting crumb exclusion
  • Issue #26 automatic detection and filling of parameters from payload
  • RSpec 3.0 compliance


  1. Unknown User (carlspring)


    It does not immediately become clear on this page what the URL should look like when posting. I had to find this out through an example on another site. Could you please, make this a bit more understandable upon first read and add actual examples of how the links should look like?

    Many thanks in advance!

    1. Unknown User (elvanja)


      The URL you post to is related to your Jenkins server root URL.
      Let's say that your Jenkins instance is available @ http://jenkins.mydomain.local.
      Then, the post URL would be http://jenkins.mydomain.local/gitlab/build_now.

      If you just enter that in a Gitlab project's hook, the rest should work out of the box.
      This is because post data from Gitlab contains all the information related to the project and branch being pushed.

      So essentially, you just append "/gitlab/build_now" or "/gitlab/notify_commit" to your Jenkins base URL.
      I'll try to update the wiki to make it more clear.
      Hope this helps!

  2. Unknown User (steffeng)

    Vanja, does it work with merge request webhooks too?

    I would like to trigger a Job if there is a match of the merge request's data and my build job:

    • url of the Gitlab repo
    • Gitlab "source_branch" => Jenkins "Branches to build"
    • Gitlab "target_branch" => Jenkins "Merge before build" (if checked) => "Branch to merge to"

    Bonus: A comment to the merge request showing the build result.

    Anything you did with your plugin next to that?

    1. Unknown User (elvanja)

      There are no plans for supporting merge requests at this time, sorry.

      The reason is that merge request payload from Gitlab does not contain information from which I can extract details about e.g. which repository was affected.

      I'd need to add ability to contact Gitlab API for that, but haven't figured out how to add global plugin configuration yet.

      If I find the time to figure that one out, then I'd be inclined to support this as well.

      1. Unknown User (mrmicks)

        Is there any update on this? I think that the repository information is now included in the information provided by Gitlab.

  3. Unknown User (inger)

    Is the GitlabHook expected to work with 1) Multi-SCM and 2) Use other projects SCM  (https://wiki.jenkins-ci.org/display/JENKINS/Template+Project+Plugin)?

    If not, is there any chance to support these? I'd be interested to contribute it, if it's a reasonably straightforward.

    Thanks for the great plugin!

    1. Unknown User (elvanja)

      Well, if the project is configured as multiscm, but you still want to trigger Git commit related build, I guess it can be done.

      I suspect it even works right now, but am not sure.

      As for other projects SCM settings, I guess it could be done.

      There is not much interest for these options at my dev shop but if you want to give it a try, why not?

  4. Unknown User (varmitslayer)

    What is this particular Jenkins plugin licensed under? I do not see a license listed on this page, nor on its GitHub page as well. Thanks!

    1. Unknown User (elvanja)

      I haven't thought much about licensing.

      I guess Jenkins licence will do just fine.

      That helps?

  5. Unknown User (xcoble)

    Would it be possible to have this plugin look at the "additional behaviors" before firing a build after a notify_commit post? ie. "polling ignores commits in certain paths"

    The use case for me is that I have a repo that stores job dsl scripts which contain about 4 seed scripts. All together these create/update about 80 jenkins jobs. i want to only execute a job dsl script if it changes. ie. don't execute it if the readme changes.

    I was able to implement a work around by adding an execution manager job which runs a system groovy script and looks at the changesets and conditionally triggers 0 or many jobs that execute a job dsl script.

    1. Unknown User (elvanja)

      So you'd like to make the build a bit more smart, e.g. like "hey, build the project only if source code was changed, and not some XY configuration or readme".

      The problem is, e.g. in my projects, we have some configurations, and even though the source hasn't changes, we still want to build and push configuration artifacts to repository.

      Besides, this plugin only triggers the build, maybe it would be better to add this kind of option to the Git plugin itself? (that performs the build)

      If nothing else, I can imagine this "trigger action" being a script, for which the result could determine if the build is to be triggered or not.

      But, then I'd have to get the changes and see what files changed, and offer the list as an input to the script.

      That sound very much like what Git plugin is already doing, so again, I think the idea is better suited there.

      Feel free to correct me!

  6. Unknown User (jivesh)

    How can i commit and push one branch of gitlab to another branch? 

    1. Unknown User (elvanja)

      Well, this is not really a responsibility of this plugin or gitlab or jenkins for that matter.

      Since your project is Git related, you can always do it yourself with regular Git commands.

      If that is not your cup of tea, you can also create pull requests on Gitlab.

      There's a bunch of ways to do it, depending on your exact needs.

      Hope this helps.

  7. Unknown User (arpitgold)


    I have set up gitlab hook as explained in Documentation.

    I have a job with parameters. I have setup push event on it.

    When there is any push on branch it triggers a build but it does not use any parameter.

    It ignores parameters.

    Can you please help me, where i am missing anything ??

    1. Unknown User (elvanja)


      For all parameters to be saved to build job when triggering it from gitlab, you need to use the plugin version from source code (build it yourself).

      The next release (in a month or so) will include that feature, but for now the above solution is the only one.

      1. Unknown User (arpitgold)

        Hi Vanja,

        I could not find any plugin version, could you please let me know, what does it means "use plugin version". and where I can find it.

        1. Unknown User (elvanja)

          It's not "use plugin version" but "use plugin version from source code".

          Which means:

          • clone the repository
          • install ruby
          • bundle gems
          • run build

          This is all described in jenkins ruby support (don't have the link).
          But it does mean that you need to build the plugin yourself.
          After this, you'll get a file you can upload to jenkins and that way install the non-released version.
          If this is too much trouble, just wait for the next release.

          1. Unknown User (arpitgold)

            Oh got it.

            Alternatively, can you just build a new build at https://jenkins.ci.cloudbees.com/job/plugins/job/gitlab-hook-plugin/

            It will also create a hpi to use. It will be more meaning full to me and other as well.

            Thanks for your quick response.

            1. Unknown User (elvanja)

              Well, it seems there is an option to deploy a snapshot version.

              Just did that, and it's available at http://repo.jenkins-ci.org/snapshots/org/jenkins-ci/ruby-plugins/gitlab-hook/1.2.0-SNAPSHOT/

              Feel free to try it out.

              1. Unknown User (arpitgold)

                Hi Vanja,

                Thanks for your quick.

                I uploaded and snapshot version. but It does not solve the issue. It still not picking job parameters.

                Can you please help me regarding same.

                1. Unknown User (elvanja)

                  OK, please open an issue on Github project's page.

                  And give me more details on how is your Jenkins project configured, maybe it's XML configuration or a screen shot or anything I can use to replicate the issue.

  8. Unknown User (thecrumb)

    I'm getting started with Jenkins and am running into one issue...

    I have my GitLab setup with a build_now hook that kicks off my Jenkins job.  The problem is I have several Jenkins jobs

    1. Deploy project
    2. Run unit tests on project
    3. Run integration tests

    And my code / tests are in the same project/branch so what happens is these all get kicked off in seemingly random order. 

    I had also added a post build action to build the others if each is successful so it ends up running things twice :)

    Ideally the hook would kick off my deployment, if that's successful then it would kick of my tests, etc. but I'm not sure of the correct way to wire that up.

    1. Unknown User (elvanja)

      Hi Jim,

      You can just configure the other project to skip notify commit (in Git section).

      That way, the hook will not trigger the builds for them and you can use your post build action to trigger the build from main project.

  9. Unknown User (edrandall)

    In GitLab, for each project I've configured the hook http://_our_jenkins_server_/project/Team3-Checkins/_projectname_

    Can you please explain the usage of the configuration:
    1. All allow all branches (Ignoring Filtered Branches)
    2. Filter branches
    3. The difference between the two alternate hooks build now and notify commit and the explicit project one. I couldn't get build now nor notify commit to do anything.

    In my case Filter branches is completely blank and I can't add anything to it.
    Under Source Code Management, Git I have a Repository URL set correctly and an explicit Branch Specifier refs/heads/teamdev configured.
    I'd like my builds to only be triggered on a commit to refs/heads/teamdev but they are being triggered whenever there is a push to any branch.
    Worse, Jenkins is then building that wrong branch - resulting in the wrong artifact getting into my maven Artifactory.

    Using Jenkins 1.580.3 with Git-Plugin 2.3.5, GitLab Hook plugin 1.3.1 and GitLab plugin 1.1.15

    1. Unknown User (edrandall)

      Sorry please scrap that comment;  I think the issue was caused by excess overlapping plugins confusion syndrome
      This now works as expected, sending down the correct branch name and only the branch we want is built when pushed.

      I uninstalled The GitLab plugin 1.1.5, removed the hook http://_our_jenkins_server_/project/Team3-Checkins/_projectname\_ (http://_our_jenkins_server_/project/Team3-Checkins/_projectname_)
      and just used the hook http://_your-jenkins-server_/gitlab/build_now - it didn't seem to work when I tested it because the GitLab test button sends down the master branchname.
      Watching the Jenkins logs at http://_your_jenkins_server_/log/all is the key to understanding what's happening.

      This is a great plugin, no additional Jenkins per-project configuration is needed as far as I can tell (not sure how that would work if I wanted a project to ignore a URL hook though).

  10. Unknown User (projectinfinity)

    Ever since an update of Jenkins I assume since I have tried every Gitlab Hook plugin version since 1.2.0 without success the error below is thrown.

    I am running Gitlab hook plugin 1.4.0 and Jenkins 1.612. Please help, nothing builds anymore as this error appears just after matching a project.

    Link to error:http://pastebin.com/raw.php?i=sH0MjitE

  11. Unknown User (dserodio)

    I've read the "Polling must die: triggering Jenkins builds from a git hook" post, but I still don't understand the motivation behind this plugin.

    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).

    What are "projects that are mostly polling (no hooks)"?

    1. Unknown User (elvanja)

      Pooling projects are the ones that don't have hooks setup, but are using scheduled polling to get new stuff from SCM.

      E.g. for TFS we couldn't setup hooks, so polling was the only option (e.g. every 15 minutes).

      1. Unknown User (dserodio)

        Ok, so why does "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)." ?

        A large number of jobs using polling will delay triggering of a job that's using hooks?

        1. Unknown User (elvanja)

          Yep, polled projects trigger polled jobs which go into build queue. Can't remember the details anymore but we were having situations where polled jobs were being triggered e.g. every 5 minutes, but executed anywhere from 1 minute after schedule up to 1 hour or so. This would effectively make a developers commit be built with a great delay. Same goes for build jobs that are triggered but use "schedule" options as opposed to "build now". That's the basic motive behind using the build now trigger with this plugin. Another issue with polled projects is that you can poll only one branch, and you get builds that are related to multiple commits. This way, you get one build per commit, whichever branch. Hope this helps.

        2. Unknown User (edrandall)

          A project which is Polling is performing the following in Jenkins, every n minutes:

          1. connect to SCM (subversion for example)
          2. Query for log of recent changes snice last-known change
          3. disconnect from SCM
          4. If there was a change, queue up a build job for the project.

          A project that is using Hooks works like this:

          1. User commits change to SCM
          2. SCM is configured to make a network request (REST request or whatever) to Jenkins URL with details of the change
          3. Jenkins determines which project(s) that change relates to, and queues up a build job for each project.

          Most of the time there are no SCM changes, so as you can see polling just imposes additional wasted load on your Jenkins and SCM servers.  Imagine if you have 150 projects all doing that!  It might take 30 seconds to do each one especially if the network or SCM server is slow.  If those projects are all configured to poll every 15 minutes there may always be one more projects doing a poll at any given time time, 24x7.   Things will slow down.  A project will not get built until there is an actual change AND it has a turn at doing its poll.

          Compare that to a hook.  No extra load.  All is quiet. User makes a commit, Jenkins is notified immediately.

          On the other hand, polling is easier to set up.  It's done all on the Jenkins side, you don't need any level of admin access to the SCM server. 

          You might have a central company Jenkins server with a mix of projects, some newer ones using Git as their SCM but many legacy projects using SVN.  If you only have administrative access to the Git server but not to SVN, you'd set up hooks for the Git projects but for the SVN ones you'd be stuck with polling.  In that situation you'd have a large number of projects (mostly polling), whilst a few are able to benefit from using hooks.

          Hope this helps.

  12. Unknown User (rlagoue)

    When do you expect to publish the next release. Since I am waiting this fix for long time now :-)
    Thanks for the great work

    When do you expect to publish the next release. Since I am waiting the fix of JENKINS-28452 for long time (about 4 months) now :-)

    Thanks for the great work

  13. Unknown User (jaycraft)

    Is there a way to trigger a build when using the Jenkins Folders plugin?  I'm trying to trigger jobs with a Gitlab webhook using this plugin.  It works great with jobs outside of folders e.g.  https://jenkins.myserver.com/gitlab/build_now/<projectname>

    However, jobs inside of folders have an extended url that looks something like


    I've tried every combination of https://jenkins.myserver.com/gitlab/build_now/<foldername>/<projectname> or that url with "job" in between the folder and project, etc.  But nothing works.  Is there some other way to access a job via webhook when it resides inside of a folder?

  14. Unknown User (colinlabs)

    payload can't use dot(.) match

    project.namespace had value docker, Jenkinsfile Don't recognize this parameter


    node() {
        stage('build') {
            checkout scm
            echo "${repository_name}"
            echo "${project.namespace}"