BuildMaster Documentation

CI Badge API

  • Last Modified: 2019-07-18

The CI Badge API offers a simple way to allow external tools to query build status in order to generate a "CI Badge" with a helpful link directly to the build or deployment execution that the status on the badge refers to.

API Usage

Each of these endpoints require that an API Key with CI Badge access is supplied with each request. The examples use a query string for simplicity since most rendered versions will be directly rendered to a web page, but you could also use a header, form value, or JSON property. See API Access & API Keys for more information.

As a best practice, API keys used for the CI Badge API should only allow access to the CI Badge API, and should not have access to any other APIs because they will be visible to anyone with access to the external system.

Endpoint Specifications

This endpoint receives data entirely as key/value parameters, which may be specified in both the querystring (recommended) but also body (application/x-www-form-urlencoded); duplicate keys will result in undefined behavior.

Endpoint Arguments

The arguments to both endpoints are the same, an API key (supplied as key or API_Key), and additional "OData-style" intersectional (i.e. AND'ed) filters to locate a matching build:

Argument Description
$ApplicationName (indexed) The latest execution of the latest build of the latest release in the specified application name
$ApplicationId (indexed) The latest execution of the latest build of the latest release in the specified application ID
$ReleaseNumber (indexed) The latest execution of the latest build of the specified release number; it is recommended to supply an application specifier with this argument
$BuildNumber (indexed) The latest execution of the specified build; it is recommended to supply an application specifier with this argument
$CustomVariable Using a custom variable name and value pair as an argument will locate a build with a matching variable value in context. Common examples are $GitCommit, $Branch, $Tag such that the first build found that matches this specified build variable and value will be used for the badge status.

Refer to the examples section for more information and use-cases.

Image Endpoint

GET /api/ci-badges/image

If successful, returns the 200 status with the content of an SVG image (content type image/svg+xml, or gzip if compression is supported by the client) representing the status of the queried build, one of the following:

Badge Conditions
Success Latest matching build execution completed successfully
Pending Latest matching build execution created but hasn't started yet
Running Latest matching build execution is in progress
Warning Latest matching build execution completed with at least one warning
Error Latest matching build execution completed with at least one error
Unknown No matching builds found.

This endpoint will always return a 200 unless the API key is not valid or unauthorized, resulting in a 403.

GET /api/ci-badges/link

If successful, returns the 303 redirect status with the Location header to a page within BuildMaster depending on the page argument:

"Page" argument Redirect Page
build (default) Build Overview page
release Release Overview page
application Application Overview page
execution Execution details page, either for a specific execution ID or the latest execution to first stage for matching build

A successful matching build will result in a 303 redirect, and other errors will result in a 400 or 403.

Examples

  • HTML
  • GitHub README Markdown
  • GitLab Project/Group
<a href="https://buildmaster.inedo.com/api/ci-badges/link?key=badges&$ApplicationName=Windows" rel="nofollow">
  <img alt="Build status" src="https://buildmaster.inedo.com/api/ci-badges/image?key=badges&$ApplicationName=Windows" />
</a>
[![Build status](https://buildmaster.inedo.com/api/ci-badges/image?key=badges&$ApplicationName=InedoCore)](https://buildmaster.inedo.com/api/ci-badges/link?key=badges&$ApplicationName=InedoCore)

Under Settings ยป General of a project or group:

Link:

https://buildmaster.inedo.com/api/ci-badges/link?key=badges&$ApplicationName=%{project_path}

Image URL:

https://buildmaster.inedo.com/api/ci-badges/image?Key=badges&$ApplicationName=%{project_path}

If the application name doesn't match exactly, simply add an Application-scoped configuration variable that matches the project name, and filter by that variable name instead.

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.

Generated from commit 2fde8bec on master