Badge Request: GitHub Check Runs Status

[calebcartwright]

📋 Description
Status badge for check runs from GitHub.

• Which service is this badge for e.g: GitHub
• What sort of information should this badge show?
  

🔗 Data

• Is there a public API? Yes
• Does the API require an API key? Our typical GitHub auth approaches will work. Note that the v3 version of the Checks API requries a custom media type (application/vnd.github.antiope-preview+json) in the request header.
• Link to the API documentation. https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref

API path would be: /{{owner}}/{{repo}}/commits/{{branch}}/check-runs?check_name={{name}}

For example:
https://api.github.com/repos/rust-lang/mdBook/commits/master/check-runs?check_name=Rustfmt

🎤 Motivation

Check Runs (and Check Suites) reflect the status of various GitHub Apps/Integrations/Services/etc. and are most often seen in the Checks tab for a PR. See an example here in our repo which includes LGTM and Netlify.

The primary use case I'd envision for this badge would be for a specific Job status as part of the GitHub Actions ecosystem. GitHub Workflows consist of one or more Jobs (and Jobs consist of a sequence of tasks/steps, where each step can run a command or action).

We already have the Workflow status badge, but a Check Runs status badge would allow for Job-level status badges too (plus it could be used for any other Check Run status)

[mbtools]

Furthermore, the GH check-status API can return "pending" although the state of the branch/commit is "green". As noted in https://github.community/t/state-is-pending-statuses-are-missing-with-github-api-v3/14386/2, GH support recommend using the check-runs or check-suites API instead.

I shall attempt a PR for this :-)

[SerpentBytes]

If no one is working on this issue, I would like to work on this. Thank you.

[mbtools]

There's PR #7759 for it already 😃

[PyvesB]

Furthermore, the GH check-status API can return "pending" although the state of the branch/commit is "green". As noted in https://github.community/t/state-is-pending-statuses-are-missing-with-github-api-v3/14386/2, GH support recommend using the check-runs or check-suites API instead.

@mbtools just trying to wrap my head around all these different concepts. Is this new check runs badge effectively a replacement for the existing check status one? Or are there notable differences in what they represent?

[mbtools]

In the most simple terms, the new badge will match the green check, yellow dot, or red cross that you see in GitHub next to a commit.

If the commit is the head of a branch or tag, you get the corresponding latest status.

[PyvesB]

Sorry, I'm still not clear... What would you recommend we do with the existing GitHub pull request check state and GitHub tag checks state badges? Do they still provide any value with the introduction of the "check runs" badges? Do they even work (your previous message suggests maybe not, but the link is apparently dead)?

[calebcartwright]

my understanding was that the various options provide the flexibility/granularity to see both the aggregate rolled up status as well as the status for individual items, and that there were use cases and user desire for both

[mbtools]

Indeed. The new service works on repo level. It is therefore suitable to include such badge into READMEs for showing the latest status.

In contrast, the other services require a workflow or pull request so show only the status of one particular object.

[PyvesB]

New badge: GitHub tag checks runs, /github/checks-runs/{user}/{repo}/{tag}
Old badge: GitHub tag checks state, /github/checks-status/{user}/{repo}/{ref}

Don't both of these allow checking the state of one particular object, a tag?

[mbtools]

Similar but not the same: Here's the best explanation I could find: https://stackoverflow.com/a/72312617

Imho, the description of the existing badge (#5973) should be changed to "GitHub tag status", "GitHub commit status", "GitHub branch status".

Check runs are closely aligned with GH action and therefore preferred. To distinguish the new services (#7759) some more, I added an optional name filter so you can show the status of one particular check run (as was requested somewhere).

[PyvesB]

Thanks for linking to those resources!

Imho, the description of the existing badge (#5973) should be changed to "GitHub tag status", "GitHub commit status", "GitHub branch status".

This makes sense to me. I also think we should add a description to those existing badges, possibly along the following lines:

Displays the status of a (tag|commit|branch), as reported by the Commit Status API. Nowadays, GitHub Actions and many third party integrations report state via the Checks API. If this badge does not show expected values, please try out our corresponding Check Runs badge instead. You can read more about status checks in the GitHub documentation.

What do you think?

[mbtools]

Sounds good. I will adjust the GH commit status in a separate PR.

PS: It will have to wait until GH check run PR is merged because it comes from the main branch of my fork. I usually do branches but didn't think ahead here.

[PyvesB]

The new badges are now live in production! 🎉