The Relicans

Kirk Haines
Kirk Haines

Posted on • Updated on

GitHub Workflow Badges

You go to a repo in GitHub in your browser, and there, right at the top of the README, is a badge:

badge

It shows the status of a Github Action, right there inside the README.

"I want to do that!", you exclaim to yourself. This is followed quickly by, "How do I do that!?"

You may land on this doc or that doc to tell you, but unless you pay attention, you may still find that you do it wrong and it doesn't work the first time.

This is because there are actually two different URL paths that can be used to access a badge, but none of the documents that I have encountered seem to acknowledge this, which can be very confusing to a reader who doesn't realize this.

So, in the interest of brevity, here it is. You can access the badge for a GitHub action using either the file name that defines the action, or using the name of the action itself, as defined inside the action.

To use the action filename, format your markdown like this:

![<LABEL>](https://github.com/<OWNER>/<REPOSITORY>/actions/workflows/<WORKFLOW_FILE>/badge.svg)
Enter fullscreen mode Exit fullscreen mode

So, as an example, the above badge can be accessed as:

![Evita CI](https://github.com/wyhaines/evita/actions/workflows/ci.yml/badge.svg)
Enter fullscreen mode Exit fullscreen mode

To use the workflow name, which is the name that you give the workflow inside of the YAML file, with a line like this:

image

The pattern is this:

![<LABEL>](https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg)
Enter fullscreen mode Exit fullscreen mode

Note that the actions/ has been removed from the URL.

As an additional example, the badge at the top of this article can be accessed via this pattern with the following markdown:

![Evita CI](https://github.com/wyhaines/evita/workflows/Evita%20CI/badge.svg)
Enter fullscreen mode Exit fullscreen mode

Just follow one pattern or the other, and you can insert your own badges.

There is one other option that should be mentioned, however, because of its flexibility -- shields.io.

This is a free badging service that lets one generate many different kinds of badges for a large number of services, including your own services. It also lets one customize the appearance of the badges with different styles, and unlike GitHub, the badges can be generated as a PNG instead of just as an SVG, which can be useful for embedding in places, like this web site, that do not allow SVG images.

Evita CI

The documentation of all of it is beyond this article. Take a look at their web site for the details, but to use their service to generate a badge like the native Github badges:

![<LABEL>](https://img.shields.io/github/workflow/status/<OWNER>/<REPOSITORY>/<WORKFLOW_NAME>?style=flat&logo=github)
Enter fullscreen mode Exit fullscreen mode

Happy badging!


I stream on Twitch for The Relicans. Stop by and follow me at https://www.twitch.tv/wyhaines, and feel free to drop in any time. In addition to whatever I happen to be working on that day, I'm always happy to field questions or to talk about anything that I may have written.

Discussion (0)