- Query Parameters
- Parameter Resolver
- Pipeline (DSL)
- Text variant
- Extension points for plugin developers
This plugin provides customizable badges (similar to shields.io) to any website. A text variant is also available that returns the build status as text.
For each variant there are two URLs available for inclusion:
-
protected exposes the badge to users having at least
Read
permission on the job:Example:
http://<jenkinsroot>/path/to/job/badge/icon?...
(for jobs)
http://<jenkinsroot>/path/to/job/<buildNumber>/badge/icon?...
(for builds)If you omit any query parameter the default badge for the job/build will be returned:
-
unprotected exposes the badge to users having at least
ViewStatus
permission on the jobExample:
http://<jenkinsroot>/buildStatus?...
To select a specific job and build use the query parameters job and build
Customization can be done via query parameters.
Four badge types are supported by the badge variant:
This style returns the standard Jenkins "balls".
Supported sizes are: 16x16
, 24x24
, 32x32
and 48x48
(and probably more... just try).
Examples: ball-16x16
or ball-32x32
Note: If you are using this style all other query parameters will have no effect.
You can add pre-customized badge configurations via pipeline script (see "DSL" below).
The customized examples above uses the following query parameters:
?subject=Custom Text&status=My passing text
You can override the color using the following valid color values:
- one of the values:
red
,brightgreen
,green
,yellowgreen
,yellow
,orange
,lightgrey
,blue
- a valid hexadecimal HTML RGB color without the hashtag (e.g.
FFAABB
). - any valid SVG color name
Note: This parameter is only supported for the unprotected URL!
The path for the selected job or any selector implemented via JobSelectorExtensionPoint
If you omit this parameter you can customize any "untethered" badge you like.
Important
The job selector string must be URL escaped.
If you are using Multibranch Pipelines the branch within the selector needs to be URL encoded twice.
Example
?job=path/to/job/branch/path
❌
would become
?job=path%2Fto%2Fjob%2Fbranch%252Fpath
✔
Select the build. This parameter is supported for the protected and unprotected URL! For the unprotected URL use the job parameter is also required!
Allowed selectors are:
-
Build-ID (
integer
) -
relative negative Build-Index (
0
= last,-1
= previous,-2
...) -
Selector via the following Rule:
(last|first)[Failed|Successful|Unsuccessful|Stable|Unstable|Completed][:${params.<BuildParamerName>=<BuildParameterValue>}]
(...)
is required[...]
is optional
Examples:
last
first
lastStable
firstCompleted
lastSuccessful:${params.BRANCH=master}
All those selectors can be concatenated as comma separated list:
build=last,-10,firstSuccessful:${params.BRANCH=master}
This searches in the last 10
runs for the first successful build of the master
branch (provided the Build Parameter BRANCH
exists).
Note: If you are using Multibranch Pipelines the branch name within the selector needs to be URL encoded twice (see job for further information).
Provide a link to be opened on clicking on the badge.
The query parameters subject
, status
, color
, animatedOverlayColor
and link
support the usage of variables like ?subject=Build ${variable}
Available builtin variables are:
-
buildId
,buildNumber
,displayName
,description
,duration
, andstartTime
-
params.<BuildParameterName>
where<BuildParameterName>
matches any Parameter used for running the job.Note: If the build parameter is not set you can use the following syntax to use a fallback value:
params.<BuildParameterName>|<FallbackValue>
Example: ?subject=Build ${params.BUILD_BRANCH|master} (${displayName})
/**
* Adds a badge configuration with the given id.
* minimal params
*
* id: A unique id for the configuration
*/
addEmbeddableBadgeConfiguration(id: <id>)
/**
* all params
*
* id: A unique id for the configuration
* subject: A subject text
* status: A status text
* color: A valid color (RGB-HEX: RRGGBB or valid SVG color name)
* animatedOverlayColor: A valid color (RGB-HEX: RRGGBB or valid SVG color name)
* link: The link to be opened upon clicking.
*/
addEmbeddableBadgeConfiguration(id: <string>,
subject: <string>,
status: <string>,
color: <string>,
animatedOverlayColor: <string>,
link: <string>)
This function returns a configuration object.
def win32BuildBadge = addEmbeddableBadgeConfiguration(id: "win32build", subject: "Windows Build")
def RunBuild() {
echo 'Sleeping instead of running the build'
sleep 10
}
pipeline {
agent any
stages {
stage('Building') {
steps {
script {
win32BuildBadge.setStatus('running')
try {
RunBuild()
win32BuildBadge.setStatus('passing')
} catch (Exception err) {
win32BuildBadge.setStatus('failing')
/* Note: If you do not set the color
the configuration uses the best status-matching color.
passing -> brightgreen
failing -> red
...
*/
win32BuildBadge.setColor('pink')
error 'Build failed'
}
}
}
}
}
}
You can use the config
query parameter to reference the win32build
id:
http://<jenkinsroot>/path/to/job/<buildNumber>/badge/icon?config=win32build
http://<jenkinsroot>/buildStatus/icon?job=...&build=...&config=win32build
The text variant returns a string representing the build status. Build status strings returned by the text variant include:
Success
- the build succeededFailed
- the build failedUnstable
- the build succeeded but one or more tests failedAborted
- the build was canceledNot built
- the build has not yet run
More details of the valid build results are available in the Jenkins javadoc.
A Jenkins Extension annotation allows Jenkins to discover classes, instantiate them, and register them in global lists of implementations of their supertypes and interfaces. The plugin provides several extension points that plugin developers can use to extend the behavior of the plugin. The Jenkins developer documentation provides more details on extensions and how to use them.
The JobSelectorExtensionPoint
allows custom job selector implementations.
The RunSelectorExtensionPoint
allows custom run selector implementations.
The ParameterResolverExtensionPoint
allow custom ${<Parameter>}
resolver implementations.