Change to GitHub workflow badge routes

[chris48s]

🥱 TL;DR

If you have a github workflow .github/workflows/test.yml

name: Run Tests
...

You need to update your badge URL from

https://img.shields.io/github/workflow/status/<user>/<repo>/Run%20Tests
to
https://img.shields.io/github/actions/workflow/status/<user>/<repo>/test.yml?branch=main

• The key change here is that the workflow parameter is now the workflow filename, not the name: defined in yaml
• We also recommend specifying the branch param in most cases, although it is not required.

If a branch param is not supplied the badge will look first for builds on your default branch and then fall back to the latest build on any branch or ref if none are found on the default branch. This is mainly useful for "branchless" worfklows (like workflows that runs against a tags or release).

If your workflow is in a subdirectory under .github/workflows, include the subdir in the route.

https://img.shields.io/github/actions/workflow/status/<user>/<repo>/sub_directory/test.yml?branch=main

Note that the workflow filename/path is case sensitive.

❓ Why are we making this change?

This change resolves the problem reported in #8146 Some users were reporting that our badges were reporting incorrect or unexpected values in some situations.

After consulting with GitHub support, it transpired that identifying workflows using the name in the yaml file can be ambiguous in some situations and defaults to finding workflows on any branch when a branch param is not specified, rather than the default branch. Switching to identifying workflows by the workflow filename and making branch a required parameter resolves these problems. Two workflows can have the same name string in yaml, but filename is unique on a given branch. GitHub themselves have quietly switched their own native badges to using this method.

We decided that dropping the old badges (using the workflow name) and requiring users to switch to the new URLs (rather than keeping the old ones "working") was the right choice for our users because in some cases the old badges were serving data which was inaccurate or unexpected in subtle ways. Serving accurate data is the most important thing for us to prioritise.

😭 You made a breaking change! Waa

We know. We try never to do this and it is not a decision we took lightly, especially given this is one of our highest traffic badges. In general, our philosophy is: If you embedded a shields badge in your README in 2013 and the upstream service is still online, that badge should still work today. We achieve this with almost no exceptions.

Occasionally we do need to change badge routes for various reasons, but usually we keep old URLs working using redirects. In this case, it was not possible to provide a transition because the new badge route uses a different parameter.

One of the reasons we try to never do this is because we don't really have a great way to communicate a breaking change to our users or provide warning before it happens. We have no idea who uses our service. We don't ask anyone to sign up, we don't track you. Hopefully given that constraint we have done a reasonable job of this.

📚 Further Reading

• Not valid Github status badge for broken workflow #8146
• Switch GitHub Workflow Status Badge to API #4587
• switch from github workflows to github actions workflows; test [githubactionsworkflowstatus githubworkflowstatus] #8475