welcome to jenkins_badges

Latest Version: v 1.2.0

jenkins_badges is a small flask app that serves dynamic badge images based on data from Jenkins CI.

Supported Badges

Endpoint	Examples	Default
coverage/<JenkinsJob>		80% +
		20%-80%
		< 20%
		error getting coverage data

Get it now

With pip:

$ pip install jenkins_badges

Jenkins Requirements

jenkins_badges communicates with your Jenkins instance over the Jenkins API . You need to either set up up the anonymous user in Jenkins with read access or supply jenkins_badges with the credentials of a jenkins user who has read access.

For the coverage badge to work, your Jenkins instance must have the Cobertura plugin installed with coverage data being supplied to it after every successful build.

Quickstart

jenkins_badges needs to be provided with information about your jenkins instance. This can be provided as arguments to the create_app function or via a configuration file.

Supplying configuration parameters directly

1. create and run the app

import jenkins_badges

#path to your jenkins instance
base_url = "https://example.com/jenkins"

# not required if anonymous jenkins user has read access
username = "apiuser" #a user with read access
token = "6c3bde145bcda49402b6914f2353a734" #user's token

app = jenkins_badges.create_app(base_url=base_url,
                                username=username,
                                token=token)
app.run()

Output:

* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

2. Your coverage badge image should be accessible at http://127.0.0.1:5000/coverage/<JenkinsJobName>

Supplying a configuration file

1. Create a configuration file

# /home/ubuntu/.jenkins_badges
JENKINS_BASE_URL = "https://example.com/jenkins"

# not required if anonymous jenkins user has read access
JENKINS_USERNAME = "apiuser" #a user with read access
JENKINS_TOKEN = "6c3bde145bcda49402b6914f2353a734" #user's token

2. Create a JENKINS_BADGES_SETTINGS environmental variable with the path to the configuration file:

Linux:

$ export JENKINS_BADGES_SETTINGS=/home/ubuntu/.jenkins_badges

3. create and run the app

import jenkins_badges

app = jenkins_badges.create_app(from_envvar=True)
app.run()

Output:

* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

4. Your coverage badge image should be accessible at http://127.0.0.1:5000/coverage/<JenkinsJobName>

Placing into a Readme File

Displaying a badge is as easy as placing a reference into your readme file.

If your readme file uses MarkDown:

![Coverage](http://127.0.0.1:5000/coverage/<JenkinsJobName>)

If your readme file uses restructuredText:

.. image:: http://127.0.0.1:5000/coverage/<JenkinsJobName>

WSGI Example

Just like any Flask app, a jenkins_badges app can be placed on a server with WSGI support:

#exampleapp.wsgi

import os

#tell jenkins_badges where the config file is located
os.environ['JENKINS_BADGES_SETTINGS'] = '/home/ubuntu/.jenkins_badges'

from jenkins_badges import create_app

#name of app must be "application"
application = create_app()

Comparison with Shields.io API

shields.io has a simple API for accessing Jenkins coverage data, providing your Jenkins anonymous user is granted read access:

https://img.shields.io/jenkins/c/<scheme>/<jenkins host>/job/<Jenkins Job>.svg

shields.io also hard codes badge colours and the number of decimal points. jenkins_badges is more suited if you want finer control of how your coverage badge is displayed or if you only allow authenticated users to access your jenkins instance.

Responsiveness

jenkins_badges serves badge images with a “maxAge” cache-control header value of 30 seconds. It does not perform redirects to shields.io due to GitHub’s well known badge caching problems. As long as the server hosting your documentation respects cache-control headers, your badge should update on a page refresh after a jenkins build.

The responsiveness of images served by jenkins_badges has been successfully tested on readme pages hosted by GitHub.

Troubleshooting

Coverage error badge displayed

Problem communicating with Jenkins.

You can test out whether jenkins_badges will be able to communicate with Jenkins by performing the following API request:

Linux:

$ curl http<s>://<path to your jenkins instance>/job/<job name>/lastSuccessfulBuild/cobertura/api/json/?depth=2

Sample Output:

{"_class":"hudson.plugins.cobertura.targets.CoverageResult","results":{"children":[{"children":[{}],"elements":[{},{},{},{}],"name":"marbl"}],"elements":[{"denominator":1.0,"name":"Packages","numerator":1.0,"ratio":100.0},{"denominator":1.0,"name":"Files","numerator":1.0,"ratio":100.0},{"denominator":1.0,"name":"Classes","numerator":1.0,"ratio":100.0},{"denominator":5.0,"name":"Lines","numerator":4.0,"ratio":80.0},{"denominator":0.0,"name":"Conditionals","numerator":0.0,"ratio":100.0}],"name":"Cobertura Coverage Report"}}

API

The jenkins_badges API is pretty simple, consisting of one function. Under the covers, the app is divided into flask blueprints, which allows it to be easily extended in the future.

jenkins_badges is a small flask app that serves dynamic badge images based on data from Jenkins CI.

jenkins_badges.create_app(from_envvar=False, base_url=None, username=None, token=None, coverage_yellow=80, coverage_red=20, coverage_decimal_points=2)

creates the flask application object

Parameters:

• from_envvar (bool) – if True, configuration parameters are sourced from file referenced by the local JENKINS_BADGES_SETTINGS environmental variable. if False, configuration parameters are sourced from the arguments.
• base_url (str) – url of Jenkins instance. Must be supplied if from_envvar=False.
• username (str) – username of Jenkins user
• token (str) – token of Jenkins user
• coverage_yellow (int) – threshold for displaying yellow coverage colour. Coverage below this threshold and above the coverage_red threshold will be shown with a yellow background. Coverage above this threshold will be shown with a green background.
• coverage_red (int) – threshold for displaying red coverage colour. Coverage below this threshold will be shown with a red background.
• coverage_decimal_points (int) – number of decimal points displayed on badge for coverage figure.

Returns:

a flask application object

Contributing

Source code for jenkins_badges can be found here . New issues, feature requests and pull requests are all welcome.

Project info

• Changelog
• License
• Authors
• Kudos