https://github.com/jenkinsci/embeddable-build-status-plugin

Embed build status of Jenkins jobs in web pages
https://github.com/jenkinsci/embeddable-build-status-plugin

hacktoberfest

Last synced: 6 months ago
JSON representation

Embed build status of Jenkins jobs in web pages

Host: GitHub
URL: https://github.com/jenkinsci/embeddable-build-status-plugin
Owner: jenkinsci
License: mit
Created: 2012-05-09T17:51:59.000Z (over 13 years ago)
Default Branch: master
Last Pushed: 2025-03-29T09:36:25.000Z (6 months ago)
Last Synced: 2025-04-01T00:35:16.003Z (6 months ago)
Topics: hacktoberfest
Language: Java
Homepage: https://plugins.jenkins.io/embeddable-build-status/
Size: 788 KB
Stars: 171
Watchers: 105
Forks: 260
Open Issues: 15
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

          # Embeddable Build Status Plugin

- [Query Parameters](#query-parameters)

- [Parameter Resolver](#parameter-resolver)

- [Pipeline (DSL)](#pipeline-dsl)

- [Text variant](#text-variant)

- [Extension points for plugin developers](#extension-points-for-plugin-developers)

This plugin provides customizable badges (similar to [shields.io](https://shields.io)) to any website.

A [text variant](#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:///path/to/job/badge/icon?...` (for jobs) \

  `http:///path/to/job//badge/icon?...` (for builds)

  If you omit any query parameter the default badge for the job/build will be returned:

  ![Badge](src/doc/flat_unconfigured.svg "Badge")

- **unprotected**  exposes the badge to users having at least `ViewStatus` permission on the job

  Example: `http:///buildStatus?...`

  To select a specific job and build use the query parameters [job](#job) and [build](#build)

Customization can be done via query parameters.

## Query Parameters

### `style`

Four badge types are supported by the badge variant:

#### *plastic*

![Badge](src/doc/plastic_unconfigured.svg "Badge") (default)

![Customized Badge](src/doc/plastic_configured.svg "Customized Badge") (customized)

#### *flat* (default)

![Badge](src/doc/flat_unconfigured.svg "Badge") (default)

![Customized Badge](src/doc/flat_configured.svg "Customized Badge") (customized)

#### *flat-square*

![Badge](src/doc/flat-square_unconfigured.svg "Badge") (default)

![Customized Badge](src/doc/flat-square_configured.svg "Customized Badge") (customized)

#### *ball-<size>*

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**.

### `config`

You can add pre-customized badge configurations via pipeline script (see **"DSL"** below).

### `subject` and `status`

The customized examples above uses the following query parameters:

`?subject=Custom Text&status=My passing text`

### `color` and `animatedOverlayColor`

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](https://www.december.com/html/spec/colorsvg.html)

### `job`

**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 ✔

### `build`

Select the build.

This parameter is supported for the protected **and** unprotected URL!

For the unprotected URL use the [job](#job) parameter is also required!

#### *Selectors*

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.=}]`

  - `(...)` is required

  - `[...]` is optional

  Examples:

  - `last`

  - `first`

  - `lastStable`

  - `firstCompleted`

  - `lastSuccessful:${params.BRANCH=master}`

#### *Concatenation*

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](#job) for further information).

### `link`

Provide a link to be opened on clicking on the badge.

## Parameter Resolver

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`, and `startTime`

 - `params.` where `` 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.|`

Example: `?subject=Build ${params.BUILD_BRANCH|master} (${displayName})`

## Pipeline (DSL)

```groovy

/**

 * Adds a badge configuration with the given id.

 * minimal params

 *

 * id: A unique id for the configuration

 */

addEmbeddableBadgeConfiguration(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: ,

                                subject: ,

                                status: ,

                                color: ,

                                animatedOverlayColor: ,

                                link: )

```

This function returns a configuration object.

### Example

```groovy

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:///path/to/job//badge/icon?config=win32build`

`http:///buildStatus/icon?job=...&build=...&config=win32build`

![Passing](src/doc/config_example_1.svg "Passing")

![Failing](src/doc/config_example_2.svg "Failing")

## Text variant

The text variant returns a string representing the build status.

Build status strings returned by the text variant include:

* `Success` - the build succeeded

* `Failed` - the build failed

* `Unstable` - the build succeeded but one or more tests failed

* `Aborted` - the build was canceled

* `Not built` - the build has not yet run

More details of the valid build results are available in the [Jenkins javadoc](https://javadoc.jenkins-ci.org/hudson/model/Result.html#field.summary).

## Extension points for plugin developers

A [Jenkins Extension annotation](https://www.jenkins.io/doc/developer/extensibility/#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](https://www.jenkins.io/doc/developer/extensions/) and how to use them.

### `JobSelectorExtensionPoint`

The [`JobSelectorExtensionPoint`](https://javadoc.jenkins-ci.org/plugin/embeddable-build-status/org/jenkinsci/plugins/badge/extensionpoints/JobSelectorExtensionPoint.html) allows custom job selector implementations.

### `RunSelectorExtensionPoint`

The [`RunSelectorExtensionPoint`](https://javadoc.jenkins-ci.org/plugin/embeddable-build-status/org/jenkinsci/plugins/badge/extensionpoints/RunSelectorExtensionPoint.html) allows custom run selector implementations.

### `ParameterResolverExtensionPoint`

The [`ParameterResolverExtensionPoint`](https://javadoc.jenkins-ci.org/plugin/embeddable-build-status/org/jenkinsci/plugins/badge/extensionpoints/ParameterResolverExtensionPoint.html) allow custom `${}` resolver implementations.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/jenkinsci/embeddable-build-status-plugin

Awesome Lists containing this project

README