Setup Jenkins Multibranch Pipeline and Organization

This page shows how to setup Jenkins Multibranch Pipeline jobs and Organization folders.

Prerequisite

• GitBucket is running.
• Jenkins is running.
• Jenkins Multibranch Pipeline is installed.
• Jenkins Github Branch Source Plugin is installed.
• Jenkins can access to GitBucket without port number and context path, such as http://gitbucket.example.com.

To clarify the above, the requirements on the "Base URL", are very strict.

• "Base URL" is in root -> System Administration -> System Settings
• A value must be provided, otherwise it will default to localhost in URLs, which won't work for webhooks
• You MUST start Gitbucket with a custom "port" of 80 as documented here. Issue
• Jenkins MUST reach Gitbucket on port 80, it cannot go through a port mapping.
• You MUST NOT start Gitbucket with a custom "prefix" as documented here. Issue

These requirements mostly stem from certain assumptions and nuances of the Github plugin on Jenkins. For example, the plugin erroneously strips off custom ports from URL's when trying to reach Gitbucket. Also, the plugin performs URL matching on webhooks, and the webhook URL has to be an exact match of the repo URL the plugin discovered previously. There are other contributing behaviors as well. If these limitations render your use-case impossible (such as you require custom port mappings), please open a ticket.

Creating a Multibranch Pipeline job

Configure Jenkins:

1. Open Manage Jenkins - Configure System.
2. Add a server in GitHub Enterprise Servers section. API endpoint should be like http://gitbucket.example.com/api/v3.

Add a job on Jenkins:

1. Open New Item.
2. Enter job name and mark as a Multibranch Pipeline. Then, click OK.
3. Add a GitHub source in Branch Sources section.
   • API endpoint: select GitBucket (http://gitbucket.example.com/api/v3).
   • Credentials: required if anonymous access is denied on GitBucket.
   • Owner: user or group
   • Repository: select your repository
4. Click Save.

Configure a webhook on GitBucket:

1. Open your repository - Settings - Service Hooks.
2. Click Add webhook button.
3. Fill followings and save.
   • Payload URL: http://jenkins.example.com/github-webhook/
   • Which events would you like to trigger this webhook?: Push, Pull Request

Create a Jenkinsfile on your repository:

pipeline {
  agent any
  stages {
    stage('build') {
      steps {
        sh 'echo Building ${BRANCH_NAME}...'
      }
    }
  }
}

A new build should be started immediately on Jenkins.

Creating an Organization folder

Add a job on Jenkins:

1. Open New Item.
2. Enter job name and mark as a GitHub Organization. Then, click OK.
3. Add a GitHub source in Branch Sources section.
   • API endpoint: select GitBucket (http://gitbucket.example.com/api/v3).
   • Credentials: required if anonymous access is denied on GitBucket.
   • Owner: group
4. Click Save.

Configure a webhook on GitBucket:

1. Open your group - Edit group - Service Hooks.
2. Click Add webhook button.
3. Fill followings and save.
   • Payload URL: http://jenkins.example.com/github-webhook/
   • Which events would you like to trigger this webhook?: Push, Pull Request

Then, your group and repositories should be shown in Jenkins.

For better security

Configure GitBucket:

1. Open System settings and set Anonymous access to Deny.
2. Create jenkins user and add it to your group.

Configure Jenkins:

1. Open Credentials - Add Credentials.
2. Fill followings and save.
   • Username: jenkins
   • Password: password of jenkins
   • Description: GitBucket access credential

Then, fix jobs to use credentials.

Pitfalls

Jenkins tries to clone from the wrong URL and uses an old Git client

If your build fails with the following message:

hudson.plugins.git.GitException: Command "git fetch --no-tags --progress http://servername/Owner/Repo.git +refs/heads/master:refs/remotes/origin/master" returned status code 128:
stdout:
stderr: error: RPC failed; result=22, HTTP code = 404
fatal: The remote end hung up unexpectedly

Then, this is caused by Jenkins trying to fetch from the Git repository under the URL http://servername/Owner/Repo.git instead of http://servername/git/Owner/Repo.git. GitBucket provides a redirect from the former to the latter URL, but this is not supported by older versions of Git.

A solution can be to install a newer Git client on the machine doing the checkout.

See also

• Branches and Pull Requests - jenkins.io