209

Is there a way to show the Jenkins build status on my project's GitHub Readme.md?

I use Jenkins to run continuous integration builds. After each commit it ensures that everything compiles, as well as executes unit and integration tests, before finally producing documentation and release bundles.

There's still a risk of inadvertently committing something that breaks the build. It would be good for users visiting the GitHub project page to know the current master is in that state.

4

14 Answers 14

178

Ok, here's how you can set up Jenkins to set GitHub build statuses. This assumes you've already got Jenkins with the GitHub plugin configured to do builds on every push.

  1. Go to GitHub, log in, go to Settings, Developer Settings, Personal access tokens and click on Generate new token.

    screenshot of generate new token

  2. Check repo:status (I'm not sure this is necessary, but I did it, and it worked for me).

    screenshot of generate new token

  3. Generate the token, copy it.

  4. Make sure the GitHub user you're going to use is a repository collaborator (for private repos) or is a member of a team with push and pull access (for organization repos) to the repositories you want to build.

  5. Go to your Jenkins server, log in.

  6. Manage JenkinsConfigure System

  7. Under GitHub Web Hook select Let Jenkins auto-manage hook URLs, then specify your GitHub username and the OAuth token you got in step 3.

    screenshot of Jenkins global settings

  8. Verify that it works with the Test Credential button. Save the settings.

  9. Find the Jenkins job and add Set build status on GitHub commit to the post-build steps

    screenshot of Jenkins job configuration

That's it. Now do a test build and go to GitHub repository to see if it worked. Click on Branches in the main repository page to see build statuses.

sceenshot of the main page where you click on 'branches'

You should see green checkmarks:

screenshot of GitHub branches with build status

15
  • 8
    This does not seem to work with Jenkins > 1.609 and Github plugin v 1.13.3 - I cannot find the option "Let Jenkins auto-manage hook URLs"
    – endre
    Nov 12, 2015 at 12:21
  • 2
    I concur with @pyeleven. I'm using Jenkins LTS 1.625.3 with Github Plugin 1.16.0 and Github API Plugin 1.71. This options does not show up. Rather I see a drop down for credentials, but no credentials are listed (even though I have credentials set up). These credentials appear when going to Advance-> Manage Additional Github Actions -> Convert Login and Password to Github token.
    – shehzan
    Jan 19, 2016 at 16:22
  • 5
    This appears to be out of date; the post-build action this answer mentions is now marked as deprecated and there's a second one
    – Daenyth
    Aug 26, 2016 at 14:32
  • 3
    Now post build step parameters has been changed. @Alex has correct answer. Nov 28, 2018 at 14:09
  • 2
    If you use the latest Jenkins Blue Ocean plugin with GitHub to create a multi-branch pipeline, it does this automatically for you, provided you set up the token correctly with the necessary permissions described in this answer. Jul 20, 2020 at 7:16
86

In the meanwhile the UI of Jenkins and GitHub has changed a bit and it took me a while to figure out how to configure Jenkins now correctly. The explanation here is based on Jenkins version 2.121.1.

I also assume that you have already configured your Jenkins Job be triggered by a webhook or by polling. Those are the steps that I have taken to get it working:

  1. Configure GitHub: Create Personal Access Token with OAuth Scope repo:status
  2. Configure Jenkins: Configure System and add the OAuth Secret as a GitHub Server - use Secret Text as an authentication method to put the OAuth Secret in there.
  3. Configure your Jenkins Job: Add Set GitHub commit status as Post-build action. Set the Status Result to One of the default messages and statuses.
  4. Check your result on GitHub: Check if you get the build status and build execution duration on your GitHub commit.

Configure GitHub

Create Personal Access Token


Enter image description here


Enter image description here


Enter image description here


Configure Jenkins

Enter image description here


Enter image description here


Enter image description here


Enter image description here


Enter image description here


Configure Jenkins Job

Enter image description here


Enter image description here


Enter image description here


Result

You will now see the status for your commits and branches:

Enter image description here

13
  • 3
    Wow finally found a solution, thanks so much! That "Secret text" got me confused.
    – head01
    Jul 10, 2018 at 13:28
  • 2
    Update: my issue was related to the privacy of my repo. I must have an issue with my credential setup. Nov 26, 2018 at 2:37
  • 4
    Update: ultimately I discovered this only works if it was triggered by an actual git push. Running the build yourself doesn't trigger the status update correctly. Nov 26, 2018 at 4:33
  • 2
    The Manage Hooks box is highlighted but not ticked in the images above, does that mean it should be unticked when we save? Jun 12, 2019 at 0:49
  • 2
    Extremely helpful screenshots and all, but this didn't work for me. The problem was the scope of the personal access token that I had generated - it needs the Full control of private repositories access, and NOT ONLY the repo:status. Hope this helps someone!
    – Roger Oba
    Feb 9, 2021 at 7:11
35

What I did was quite simple:

  1. Install the Hudson Post Task Plugin

  2. Create a Personal Access Token here: Personal access tokens (classic)

  3. Add a Post Task Plugin that always adds success

    curl -XPOST -H "Authorization: token OAUTH TOKEN" https://api.github.com/repos/:organization/:repos/statuses/$(git rev-parse HEAD) -d "{
      \"state\": \"success\",
      \"target_url\": \"${BUILD_URL}\",
      \"description\": \"The build has succeeded!\"
    }"
    
  4. Add a Post Task Plugin that will add failure if "marked build as failure"

    curl -XPOST -H "Authorization: token OAUTH TOKEN" https://api.github.com/repos/:organization/:repos/statuses/$(git rev-parse HEAD) -d "{
      \"state\": \"failure\",
      \"target_url\": \"${BUILD_URL}\",
      \"description\": \"The build has failed!\"
    }"
    
  5. You can also add a call to pending at the beginning of tests

    curl -XPOST -H "Authorization: token OAUTH TOKEN" https://api.github.com/repos/:organization/:repos/statuses/$(git rev-parse HEAD) -d "{
      \"state\": \"pending\",
      \"target_url\": \"${BUILD_URL}\",
      \"description\": \"The build is pending!\"
    }"
    

Screenshot of the Post build task configuration

3
32

This plugin should work: Embeddable Build Status

You should be able to embed badges like this into your README.md file:

Build passing

2
  • 6
    Sadly, it seems that GitHub started caching these images on some image hosting service, and they are being displayed incorrectly now.
    – axel22
    Feb 12, 2014 at 8:59
  • Now it works fine if you've correctly set up access (anonymous user should be able to see build status) Jan 5, 2016 at 10:31
11

The Commit Status API allows you to see the "Repo Statuses API".

And since April 26th 2013, you now can see the build status on your GitHub repo branch page:

build status on GitHub repo branches

That means it is another way, by visiting the GitHub project page, to see those statuses instead of having only Jenkins.

Starting April 30th, 2013, the API endpoint for commit statuses has been extended to allow branch and tag names, as well as commit SHAs.

4
  • Where do I put the URLs to hit? Is there a Plugin or do I have to user curls in a build step? Nov 1, 2013 at 15:20
  • @IanVaughan what do you mean "to hit"? To see what? To see a status, it would be a curl (developer.github.com/v3/repos/statuses/…)
    – VonC
    Nov 1, 2013 at 21:29
  • Sorry, yep, I knew that curl could be used, and I knew the API interface, it was more of where to put the curl, and if not a higher level abstraction from curl was available? i.e. I could add a curl POST in before the build starts to state the commit/PR is building, and then one after, but this all seems very low level, and was hoping there was a higher level plugin todo this stuff for me. Nov 2, 2013 at 22:11
  • I have since found Janky, which is quite heavy for my use-case, seems to do what I want. Nov 2, 2013 at 22:12
11

There's also the plugin Embeddable Build Status that will give you a badge URL that you can post in your README.md file, and it looks like this:

Build passing

1
6

If you have the GitHub plugin installed on your Jenkins, you can do it in the Post build actions like this:

Set build status on GitHub

3
  • 14
  • 5
    This answer lacks details: how do I create an OAuth access token on GitHub to let the GitHub plugin use the APIs necessary to set build status? What permissions are needed on this token? Where in Jenkins configuration can I specify the username/token? Nov 13, 2014 at 11:00
  • 3
    This is really not helpful, how do you get to this dialog window ?
    – oz123
    Jul 4, 2017 at 10:08
6

Add the below line in your README.md file and change both URLs according to your Jenkins project.

[![Build Status](https://jenkins../..project/lastBuild/buildStatus)](https://jenkins../..project/lastBuild/)
2
  • Is the graphic loaded automatically? It seems it is not for me... Jan 30, 2020 at 12:20
  • Yes, It will not work. You have to refresh your page.
    – Kaushal
    Feb 5, 2020 at 12:09
3

In regards with setting up Jenkins and GitHub's protected branch. I'm using Jenkins 2.6, and these are the steps I did to make it work:

On your repository's GitHub webpage:

  1. Navigate to Settings > Branches.
  2. Under Protect branches, click on the Choose a branch drown down menu and select the branch you want to set as a Protected branch.
  3. Enable the options as needed.

On the Jenkins Server: (Make sure you have the Git and GitHub Plugin installed)

  1. Navigate to Manage Jenkins > Configure System.
  2. Under GitHub, set the API URL to https://api.github.com. Though this is the default value.
  3. Select your generated token for the Credentials. If you haven't generated a token yet, click on Advanced... then on Additional actions, you can convert your login and password to token and use it as your credential.

Also, make sure the GitHub account that your Jenkins is using is a collaborator for the repository. I've set it with write permission level.

Hope this helps.

3

For pipeline projects, you can use the post section like so:

void setBuildStatus(String message, String state) {
  step([
      $class: "GitHubCommitStatusSetter",
      reposSource: [$class: "ManuallyEnteredRepositorySource", url: "https://github.com/my-user/my-repo"],
      contextSource: [$class: "ManuallyEnteredCommitContextSource", context: "ci/jenkins/build-status"],
      errorHandlers: [[$class: "ChangingBuildStatusErrorHandler", result: "UNSTABLE"]],
      statusResultSource: [ $class: "ConditionalStatusResultSource", results: [[$class: "AnyBuildResult", message: message, state: state]] ]
  ]);
}

pipeline {
    agent any

    triggers {
        githubPush()
    }

    stages {

        stage('Hello') {
            steps {
                echo 'Hello World'
            }
        }

    }

    post {
        success {
            setBuildStatus("Build succeeded", "SUCCESS");
        }
        failure {
            setBuildStatus("Build failed", "FAILURE");
        }
    }
}

Just change "https://github.com/my-user/my-repo" to meet your GitHub repository.

Reference: How to set GitHub commit status with Jenkinsfile NOT using a pull request builder

2

I followed the directions from Alex and it worked.

But, for GitHub Enterprise you need to modify the API URL when adding the server to Jenkins.

For example, if your company is creditcard.com, your URL would be

https://github.creditcard.com/api/v3/

1

Jently updates your GitHub commit status (as described by vonc), but unfortunately they have yet to implement the Repo Status API.

1
  • 1
    Jently supports the Github's Status API now.
    – kroiz
    Sep 20, 2016 at 18:10
1

I'm no longer using this approach. Please use one of the other answers.

What I ended up doing, for our specific case: (the previous answers were great - thanks!)

Because our build server is not on the Internet, we have a script to publish the build status to the gh-pages branch on GitHub.

  • Start of build stamps failing
  • End of build stamps success
  • Project runs after main project to publish results -> build-status, API docs, test reports and test coverage.

GitHub caches images, so we created a .htaccess file, that instructs a short cache timeout for the build-status image.

Put this in the directory with the build-status image:

ExpiresByType image/png "access plus 2 minutes"

Here's the build script. The target that publishes to gh-pages is '--publish.site.dry.run'

With less than 400 lines of configuration, we have:

  • Compile checks
  • Unit & integration tests
  • Test Reports
  • Code Coverage Reports
  • API documentation
  • Publishing to GitHub

. . and this script can be run in or outside of Jenkins, so that:

  • Developers can run this script before commit, reducing the chance of a broken build that impacts others.
  • A failure is easy to reproduce locally.

The Results:

Project main page has the build status, updated after each build, along with latest API documentation, test results and test coverage.

4
  • Great feedback, more precise than my answer. +1
    – VonC
    Dec 17, 2013 at 6:58
  • 2
    Build script link is dead
    – Saikat
    Jan 21, 2017 at 10:23
  • 1
    Do you have a live link to your script?
    – Ian
    Feb 20, 2018 at 14:39
  • Have stopped using this approach - I think the other answers will be better. Feb 21, 2018 at 1:47
0

I am adding to this answer, and also to this one. They have answered the question, but they didn't give us a proper intuition about the problem

So, here are my intuitions:

  • We need to add status to our GitHub commit. This status is based upon the results of our Jenkins build.

  • To do this, we need to give Jenkins access to the GitHub API, not to the repo. We do this through OAuth, and we can create the token going to the GitHub settingsDeveloper settingsPersonal access tokens. Then for a public GitHub repository just check repo:status, and for a private repository, check the whole repository section

  • After creating your access token you need to add it to your Jenkins server:

  • Copy and paste the access token to the GitHub plugin section settings, under your Jenkins configurations

  • Create a GitHub server. It defaults to api.github.com. And add the access token as a secret text credentials.

  • The last step is to add a post build settings when you create your pipeline.

Resources:

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.