Uploaded image for project: 'Jenkins Website'
  1. Jenkins Website
  2. WEBSITE-467

Investigate/create/add a 'Configuring a webhook to trigger Jenkins builds' tutorial for the Jenkins User Documentation



    • Type: Task
    • Status: To Do (View Workflow)
    • Priority: Minor
    • Resolution: Unresolved
    • Component/s: content
    • Labels:
    • Similar Issues:


      For a while now, I've been meaning to look into creating a tutorial about how to configure a webhook (in a web-based Git server) to trigger a Pipeline project's builds in Jenkins.

      After a recent discussion with Liam Newman, I soon realized this was going to be a much more complex task than I anticipated. The main complexities in developing such a tutorial arise from the multitude of different network combinations and configurations that could easily lead to the content of this tutorial getting lost in the weeds.

      Therefore, the aim of this tutorial is to demonstrate the processes for setting up a webhook from a web-based Git server to trigger of a Pipeline project's build in Jenkins, without covering the details of different network combinations and configs, which are beyond the scope of this tutorial. This information would need to be stated up front in the tutorial.

      Essentially, the easiest/practical path to take for this tutorial would be to assume everything is done locally on the one machine. That way, we do not have to assume 


      For this tutorial, I looked at the following web-based Git servers (ones which can be installed locally on the reader's machine and not necessarily in Docker - which complicates matters):

      • Bitbucket Server - can download a free 30-day evaluation copy and is installed locally on macOS (which I tested), Linux and Windows. Once the evaluation period expires, however, it's no longer possible to push anything to your Bitbucket Server installation. A US$10 license can be purchased to restore this functionality again.

      • Gitea and Gogs - both free and can be installed locally on macOS (which I tested), Linux and Windows. (Gitea can also run in Docker, which I didn't test).
        • With a default setup, SSH operates on port 22 by default, so I found I had to activate Remote Login from my Mac's System Preferences > Sharing area to allow me to push from a local clone to either Gitea or Gogs. (I subsequently discovered that using HTTP instead of SSH for Git communications made this unnecessary.)
        • With my Gitea setup (not Gogs), I encountered this issue and found that implementing the DB path update documented in this issue fixed the problem.

      It took me some time to realize that running Jenkins in Docker (as we do for all the other existing tutorials so far) was complicating the situation. AFAICT, since I was running the web-based Git server apps (above) directly on my host machine (i.e. localhost), my Jenkins in Docker's localhost wasn't identifying the localhost of my Git server apps running outside of Docker (see attached screenshot demonstrating what happens when I attempted to configure a valid Bitbucket Server repository URL in Jenkins in Docker).

      I even encountered similar problems attempting to get Jenkins in Docker accessing a repository in GitLab CE in Docker (all running off the same Docker host).

      Finally success!

      When I ran Jenkins directly on my own machine (i.e. from a WAR file), I was able to get webhooks configured in Bitbucket Server, Gitea and Gogs to trigger Pipeline project builds. To do this, the following prerequisites are required:

      • Bitbucket Server - the free Post Webhooks for Bitbucket add-on must be installed in Bitbucket, along with the Bitbucket Plugin for Jenkins.
      • Gitea and Gogs - the Gogs Plugin for Jenkins is required.

      Interestingly, for Gitea, there is a Gitea plugin available, which doesn't appear to work. This Stackoverflow post has more information about configuring webhooks for both Gitea and Gogs.

      Proposed tutorial outline

      This may change after I have a discussion with Damien Duportal later today (8 Feb 2018 my time), since the following is based on the assumption that all required tools/software involved are installed locally.


      • Butbucket Server, Gitea or Gogs installed locally - link off to relevant page/s, although can provide recommended running instructions (for the purposes of this tutorial).
      • Jenkins WAR file (local installation) - can probably link off to the WAR file procedure in the Installing Jenkins docs.
      • ( Only for Bitbucket Server ) An SSH public/private key pair (e.g. for your computer's main user account) is necessary for Bitbucket Server (when all is installed locally) - just setting the public key component in Bitbucket Server is all that seems to be required. This doesn't need to be done with Gitea and Gogs.


      1. Fork relevant sample repository from GitHub and clone it locally.
      2. Create an empty repository in your Bitbucket Server or Gitea/Gogs instance.
      3. Add your locally cloned repo to your local Bitbucket Server or Gitea/Gogs instance - i.e. git remote add <git-server-remote-name> <git-server-url> followed by git push <git-server-remote-name>
        Note: For simplicity, use the http://... protocol for <git-server-url>.
      4. In Jenkins:
        1. Install the relevant plugin to allow Jenkins to recognize your web-based Git server's webhook request:
          • For Bitbucket, this is the Bitbucket Plugin.
          • For Gitea and Gogs, this is the Gogs Plugin.
        2. Create your Pipeline project and for simplicity, specify the URLs to your web-based Git server's repo using the http://... protocol. (There is no need to configure any credentials here - I suspect, at least in my case, because Jenkins would be running using your computer's main user account, which is what the web-based Git server would be using too.)
          • For Bitbucket, you need to ensure the Build when a change is pushed to BitBucket option is selected.
      5. In your web-based Git server, create your webhook:
        • For Bitbucket:
          1. Install the Post Webhooks for Bitbucket add-on.
          2. Go to your repo's Post Webhooks (not Webhooks) feature and create the webhook (i.e. using http://<jenkins-server>/bitbucket-hook/ where <jenkins-server> might be localhost:9090).
        • For Gitea or Gogs, go to your repo's Webhooks feature and create the webhook (i.e. using http://<jenkins-server>/gogs-webhook/?job=<your-jenkins-job-name>).
      6. Create your initial Jenkinsfile and commit it to your local clone, then git push <git-server-remote-name> (i.e. to your local web-based Git server).
      7. Go back to Jenkins and see your Pipeline project being built without you having triggered it manually - MAGIC!
      8. Iterate over the last two steps with Test and Deploy stages.

      Caveat: Unlike the Jenkins in Docker method of installing Jenkins locally (using the jenkinsci/blueocean image), a disadvantage of installing Jenkins from a WAR file is that Blue Ocean is not installed by default.




            Unassigned Unassigned
            ggaskell Giles Gaskell
            0 Vote for this issue
            2 Start watching this issue