readme.md

Bitbucket Server Notifier Plugin for Jenkins

This Jenkins plugin notifies Bitbucket Server (formerly known as Stash) of build results. Failed or successful builds will show up as little icons in Bitbucket's web interface in commit logs. Clicking on such an icon will take the user to the specific build.

Requirements

• Stash 2.1 or newer / Bitbucket Server 4.0 or newer

This plugin uses the Atlassian Stash / Bitbucket Server Build REST API.

Setup

Set up Bitbucket Server Notifier by navigating to Manage Jenkins --> Configure System and scrolling down to the Bitbucket Server Notifier section. Enter at least your Server base URL and Credentials. Additional options are available as required.

Script setup

Either automatically upon Jenkins post-initialization or through Jenkins Script Console, example:

Jenkins
    .instance
    .getDescriptor('org.jenkinsci.plugins.stashNotifier.StashNotifier')
    .with{
        credentialsId = 'bitbucket-creds'
        stashRootUrl = 'https://my.company.intranet/bitbucket'
        ignoreUnverifiedSsl = true
        disableInprogressNotification = true
        includeBuildNumberInKey = false
        prependParentProjectKey = false
        considerUnstableAsSuccess = false
    }

Usage

Use the Bitbucket Server Notifier by adding it as a Post Step in your Jenkins build job configuration.

1. In your Jenkins job configuration go to the Post-build Actions section, click on Add post-build action and select Notify Bitbucket Instance.
2. Enter the Server base URL, e. g. http://localhost:7990 or https://my.company.intranet/bitbucket.
   If in doubt, go to your local Bitbucket server and check the URL in the browser. The URL http://georg@localhost:7991/projects e. g. reveals the server base URL, which is http://localhost:7991 in this case.
3. Select the Credentials for authenticating with Bitbucket.
   Please note that SSH credentials (public/private key) from Jenkins that might be added to Bitbucket are not used for the authentication. Typically, in order to access Bitbucket you would add a service account (username and password) to Jenkins.

That's it. If you have configured everything correctly, Jenkins will notify your Bitbucket instance of subsequent builds. The result is illustrated on the Atlassian Bitbucket Build Integration wiki page.

Note on Pipeline Plugin usage

See the following code for an example of how to use this plugin inside of a Pipeline. You must set the result of the current build manually in the Pipeline script.

node {
    checkout scm                            // Necessary so we know the current commit

    notifyBitbucket()                       // Notifies the Bitbucket instance of an INPROGRESS build

    try {
        // Do stuff

        currentBuild.result = 'SUCCESS'     // Set result of currentBuild !Important!
    } catch(err) {
        currentBuild.result = 'FAILURE'     // Set result of currentBuild !Important!
    }

    notifyBitbucket()                       // Notifies the Bitbucket instance of the build result
}

Or you could as well use

    checkout scm
    
    notifyBitbucket(buildStatus: 'INPROGRESS')        // Notifies the Bitbucket instance of an INPROGRESS build
    
    try {
        // Do stuff
        notifyBitbucket(buildStatus: 'SUCCESSFUL')    // Notifies the Bitbucket instance of an SUCCESSFUL build
    } catch(err) {
        // Do clean up
        notifyBitbucket(buildStatus: 'FAILED')        // Notifies the Bitbucket instance of an FAILED build
    }

In situations where an advanced setup is required the following can be used:

node {
    this.notifyBitbucket('INPROGRESS')     // Notifies the Bitbucket instance of an INPROGRESS build

    try {
        // Do stuff

        this.notifyBitbucket('SUCCESS')
    } catch(err) {
        this.notifyBitbucket('FAILED')
    }
}

def notifyBitbucket(String state) {
    notifyBitbucket(
            commitSha1: 'commit',
            credentialsId: '00000000-1111-2222-3333-123456789abc',
            disableInprogressNotification: false,
            considerUnstableAsSuccess: true,
            ignoreUnverifiedSSLPeer: true,
            buildStatus: state,
            buildName: 'Performance Testing',
            buildUrl: 'https://my.company.intranet/bitbucket/custom-build-url',
            includeBuildNumberInKey: false,
            prependParentProjectKey: false,
            projectKey: '',
            stashServerBaseUrl: 'https://my.company.intranet/bitbucket')

}

In Declarative Pipelines, where Jenkins sets currentBuild.result = null for SUCCESS builds, the current value can be modified via a script step, e.g.:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Hello World'
                // currentBuild.result == null here
            }
        }
    }
    post {
        always {
            script {
                currentBuild.result = currentBuild.result ?: 'SUCCESS'
                notifyBitbucket()
            }
        }
    }
}

Note on credentials

Currently Bitbucket Server Build Notifier accepts only raw plaintext credentials as it uses the HTTP REST API of Bitbucket.

Maintainers

• Georg Gruetter (Twitter, GitHub)
• Pavel Batanov (GitHub)

License

Apache 2.0 License