Gitlab CI using Badges for each job

Matt picture Matt · Aug 18, 2017 · Viewed 12.5k times · Source

Let's say I have configured multiple jobs for a project like following:

build_win32:
  script: ...

build_ios:
  script: ...

unit_tests:
  script: ...

server_tests:
  script: ...

client_tests:
  script: ...

What I want to achieve is to configure badges per each job under README.md so that I can have immediate feedback of specifically which part went wrong.

There is a Gitlab Documentation on setting badges but this has a limitation that it shows how to configure badges for build and coverage status only.

I'm wondering if there is such a build-in feature in Gitlab CI. I could use 3rd party plugins also. Any helps will be appreciated.

Answer

JGC picture JGC · Nov 17, 2017

You can achieve what you need by creating badges in your pipeline steps, registering the badge files as pipeline artifacts, and publishing them to GitLab Pages. From there you can reference the badges in your README.md

How to do what you asked

1. Generate the badge

In each of your CI steps you would need to generate badge files, and store them under public/<badge-file>.svg

You can generate badge files using http://shields.io. I have written my own Python badge generator, which can be found here: https://github.com/jongracecox/anybadge

2. Register badge as pipeline artifact

Register each of the generated badge files as artifacts in the CI job by including this in each job in the .gitlab-ci.yml:

build_win32:
  script: ...
    - <generate public/build_win32.svg>
  artifacts:
    paths:
      - public/build_win32.svg

build_ios:
  script: ...
    - <generate public/build_ios.svg>
  artifacts:
    paths:
      - public/build_ios.svg

unit_tests:
  script: ...
    - <generate public/unit_tests.svg>
  artifacts:
    paths:
      - public/unit_tests.svg

server_tests:
  script: ...
    - <generate public/server_tests.svg>
  artifacts:
    paths:
      - public/server_tests.svg

client_tests:
  script: ...
    - <generate public/client_tests.svg>
  artifacts:
    paths:
      - public/client_tests.svg

3. Publish badge to GitLab Pages

Include a new pages publish step, which deploys everything in the public directory to GitLab pages:

pages:
  stage: deploy
  artifacts:
    paths:
    - public
  only:
  - master

You shouldn't need to modify the above. Once this job runs, all the files in public will be available via the GitLab pages web server. This is often http://NAMESPACE.GITLABPAGESSERVER/project

Read more about GitLab pages here: https://docs.gitlab.com/ce/user/project/pages/index.html

4. Include badges in README.md

When the master pipeline runs for the project, the badge files are published to GitLab Pages, and can then be referenced from the project README.md.

Why this might not make sense

I understand why you would ask this question, but I would like to explain why you might not want to do that.

GitLab pipelines run on every push to the project - on every branch. Typically you would only want to generate badges for your README file from the master branch (or a release) branch, so you would restrict the pages step to only run on master@group/project.

Also consider that a pipeline will usually be configured to stop when a job errors. This would mean that if a master pipeline job failed then the badges for that pipeline would not get generated, and would therefore not be helpful in determining which job failed.

The best place to get your immediate feedback is in the pipeline view, and you could add the pipeline success badge to your readme with a link to the pipeline, usually something like https://gitlabserver/namespace/project/badges/branch/build.svg

If you still want to use the approach you have described then my suggestion would be to set each pipeline stage to allow failure. This would allow the full pipeline to run, despite failures in any job, and the badges should still get generated, and published to Pages.