Default location for CI-created custom-badges
Problem to solve
Using badges in a GitLab project is a good way to have the most important pipeline results always visible on the project page.
But currently GitLab is missing a default location to store custom-badges (for example auto-generated by CI-jobs [AnyBadge]).
One possible (but limited) location are currently the GitLab Pages [StackOverflow], but ATTENTION. SVG files of badges MUST BE part of the artifact 'pages', but ...
- Only a single artifact is currently allowed per job (https://gitlab.com/gitlab-org/gitlab-ce/issues/34954) => hence, job which returns a badge cannot have its own artifact
- Using the jobs cache for accumulate all badges is no solution, as a cache is not pushed if a job fails (https://gitlab.com/gitlab-org/gitlab-ce/issues/35805)
Hence, all badges need to be accumulated somewhere else.
- A possible solution is to use a separate branch and push the badge files from the CI jobs there. A separate job can then clone that branch and copy the files to its artifacts 'pages'. This is a complicated and error-some solution, which requires to use PRIVATE_TOKENS for enabling the runner to push to an extra branch.
- Alternative one can accumulate the badges at Dropbox (https://gitlab.com/kubouch/ci-test/tree/badges).
But that way the dependency to GitLab pages is not solved, which can be a limit.
With the future access support for GitLab Pages (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18589) they will not be a proper place for badges anymore.
Simple workarounds using single artifacts 'pages'
- Work-around No.1 using GitLab Pages
-
Generate the badge
Use a badge generator like this one in each CI-job: https://github.com/jongracecox/anybadge or https://shields.io -
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:tests: script: ... - <generate badge-tests.svg> - mv badge-tests.svg public/badge-tests_$CI_COMMIT_REF_NAME.svg artifacts: name: pages paths: - public/badge-tests_$CI_COMMIT_REF_NAME.svg
-
Publish badge to GitLab Pages
Add 'pages' job and enable GitLab Pages via Settings->Pagespages: stage: deploy artifacts: name: pages paths: - public only: - master
-
Why is this "just" a work-around
- GitLab Pages must be enabled.
- GitLab Pages must be accessible (default behavior might change with MR https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18589)
- Pipeline will usually be configured to stop when a job errors -> default badges are missing.
- Only a single artifact is allowed per job right now. This work-around will fix artifacts-name to "pages"
(perhaps this issue will bring a solution if solved https://gitlab.com/gitlab-org/gitlab-ce/issues/34954).
- Work-around: Add an extra job, which shares the same cache with the others jobs and copy the badge-files from cache to artifact 'pages' there (requires the cache to be pushed even if jobs fail -> https://gitlab.com/gitlab-org/gitlab-ce/issues/35805).
What does success look like, and how can we measure that?
- Have a special storage place to copy files for world-wide access (e.g. always_public/)
- Have a keyword for a script, which runs independent of a job failed or not (even if the precious job failed)
tests:
always_script:
- <generate badge-tests_$CI_COMMIT_REF_NAME.svg>
- cp badge-tests_$CI_COMMIT_REF_NAME.svg always_public/
Links / references
AnyBadge - https://pypi.org/project/anybadge/
StackOverflow - https://stackoverflow.com/questions/45756371/gitlab-ci-using-badges-for-each-job
Badge generation with GitLab API (JSON) and Shields.io
https://img.shields.io/badge/dynamic/json.svg?label=forks&url=https://gitlab.com/api/v4/projects/13083&query=$.forks_count&colorB=brightgreen