Badge request: Concourse

[DecentM]

Concourse is both a self-hosted and a SaaS CI solution. It has a built-in badge server, but unfortunately it only allows one badge style, which is flat.

Pipelines

If a pipeline (Concourse term which refers to a series to tasks) is set to public, a JSON API is exposed at {{concourse-url}}/api/v1/teams/{{team-name}}/pipelines/{{pipeline-name}}/jobs.

This returns an object representing the build, for example: (click to expand)

``` [ { "id": 3, "name": "test", "pipeline_name": "build", "team_name": "openusercss", "next_build": null, "finished_build": { "id": 37, "team_name": "openusercss", "name": "18", "status": "failed", "job_name": "test", "api_url": "/api/v1/builds/37", "pipeline_name": "build", "start_time": 1519336819, "end_time": 1519337102 }, "inputs": [ { "name": "repo", "resource": "repo", "trigger": true } ], "outputs": [], "groups": [] }, { "id": 4, "name": "approve", "pipeline_name": "build", "team_name": "openusercss", "next_build": null, "finished_build": { "id": 19, "team_name": "openusercss", "name": "2", "status": "succeeded", "job_name": "approve", "api_url": "/api/v1/builds/19", "pipeline_name": "build", "start_time": 1518882062, "end_time": 1518882890 }, "inputs": [ { "name": "repo", "resource": "repo", "passed": [ "test" ], "trigger": true } ], "outputs": [], "groups": [] } ] ```

The pipeline only succeeds if all `finished_build.status` items are `"succeeded"`. Thus, the badge in the above example would show `build | failed`. In my opinion and based on the guidelines, the shields.io URL for the badge should be `/concourse/{{scheme}}/{{concourse-url}}/{{team-name}}/pipeline/{{pipeline-name}}.svg` > If `team-name` is missing, it should be replaced with "main", which is the default team name in Concourse. Based on my current knowledge, it's not possible for a user not to be a member of a team. ## Individual builds If a build is set to public, a JSON API is exposed at `{{concourse-url}}/api/v1/builds/{{id}}`.

This returns an object representing the pipeline, for example: (click to expand)

``` { "id": 37, "team_name": "openusercss", "name": "18", "status": "failed", "job_name": "test", "api_url": "/api/v1/builds/37", "pipeline_name": "build", "start_time": 1519336819, "end_time": 1519337102 } ```

The build succeeds if `"status"` is `"succeeded"`. In my opinion and based on the guidelines, the shields.io URL for the badge should be `/concourse/{{scheme}}/{{concourse-url}}/build/{{build-id}}.svg` ## Comments There's potentially other uses of the API as well, like counting builds and last build time. Here are a couple of routes that may be of interest (for the sake of the examples, I'm linking my own instance of Concourse, but these work for all up-to-date installs of the service): https://concourse.decentm.com/api/v1/builds https://concourse.decentm.com/api/v1/teams/openusercss/pipelines https://concourse.decentm.com/api/v1/teams https://concourse.decentm.com/api/v1/teams/openusercss/pipelines/pull-request https://concourse.decentm.com/api/v1/teams/openusercss/pipelines/pull-request/jobs

[chris48s]

Hi @DecentM

This sounds like it would be a reasonable service to have a badge for. There is no reason not to support a self-hosted solution. There are others in the codebase for example JIRA, Discourse and Jenkins CI.

Example of a JIRA badge:

https://img.shields.io/jira/sprint/https/jira.spring.io/94.svg

It looks like you've already put some thought into what the URL structure should look like and which endpoints can serve the required data - this is a great start. Would you be interested in developing that a bit further and submitting a pull request? You could start off with a PR for a build status badge and move on to others later (in fact I'd encourage not trying to do it all at once).

There is some documentation to help get started at https://github.com/badges/shields/blob/master/CONTRIBUTING.md if you are interested in contributing. Looking at the code for something like the CodeShip or Shippable badge would probably give you a reasonable example to start from. It seems like Concourse's own instance would be sensible to target the example badges and integration tests at e.g: https://ci.concourse.ci/api/v1/builds

[chris48s]

Thinking about it, this recent PR which adds the BitBucket pipeline build status badge:

https://github.com/badges/shields/pull/1510

would be a good example to use as a base as it matches the current conventions and adds all the necessary tests.

[DecentM]

Thanks for the input!
I'm not familiar with go, but I'll look into the PR to see if I can base the changes on that.

[jake-at-work]

@DecentM have you made any progress? I'd like to help out.

[DecentM]

@pivotal-jbarrett Not anything other than getting familiar with the code, please start out and then I can chip in if needed.