Badgr
Badgr's creators love using shields.io, for displaying various project statuses in our READMEs, but it doesn't support something we wanted badly-- the ability to generate a badge based on the results of a GitHub check suite associated with a specific GitHub App.
Given a repo owner, repo name, and optional branch name, Badgr queries for GitHub check suite results, consolidates them into a single status (by selecting the "most severe"* among the results), then delegates to shields.io to serve the corresponding badge. If a GitHub App ID is also specified, the badge will reflect only the results of check suites associates with that App.
*Here is how Badgr evaluates check suite severity, from least severe to most:
- Passed: Check suite has run to completion and succeeded.
- In Progress: One or more checks in the check suite have progressed past the queued state, but not all checks are complete.
- Queued: No check in the check suite is either complete or in progress.
- Neutral: Check suite has run to completion and neither failed nor succeeded.
- Canceled: Check suite has been voluntarily terminated by a user or some other process.
- Action Required: Check suite has run to completion but some action is required from a user.
- Timed Out: Check suite has timed out.
- Failed: Check suite has run to completion and failed.
- Unknown: Badgr has been unable to determine the check suite's status.
Badgr also uses Redis to cache results to avoid getting rate limited by the GitHub Checks API. The cache is composed of warm and cold layers. The warm layer caches results short term to balance the need for up-to-date results against the desire to not be rate limited. The cold layer caches results longer term to return a relatively recent result in the event of a communication failure with GitHub.
Installation
Prerequisites:
-
A Kubernetes cluster for which you have the
admin
cluster role -
kubectl
andhelm
(commands below require Helm 3.7.0+)
1. Install Badgr
For now, we're using the GitHub Container Registry (which is an OCI registry) to host our Helm chart. Helm 3.7 has experimental support for OCI registries. In the event that the Helm 3.7 dependency proves troublesome for users, or in the event that this experimental feature goes away, or isn't working like we'd hope, we will revisit this choice before going GA.
First, be sure you are using Helm 3.7.0 or greater and enable experimental OCI support:
$ export HELM_EXPERIMENTAL_OCI=1
Since this chart requires some slight bit of custom configuration, we'll need to create a chart values file with said config.
Use the following command to extract the full set of configuration options into a file you can modify:
$ helm inspect values oci://ghcr.io/brigadecore/badgr \
--version v0.1.0 > ~/badgr-values.yaml
Edit ~/badgr-values.yaml
, making the following changes:
host
: Set this to the host name where you'd like Badgr to be accessible.
Save your changes to ~/badgr-values.yaml
and use the following command to
install the gateway using the above customizations:
$ helm install badgr oci://ghcr.io/brigadecore/badgr \
--version v0.1.0 \
--create-namespace \
--namespace badgr \
--values ~/badgr-values.yaml
2. (RECOMMENDED) Create a DNS Entry
If you installed the gateway without enabling support for an ingress controller, this command should help you find the gateway's public IP address:
$ kubectl get svc badgr \
--namespace badgr \
--output jsonpath='{.status.loadBalancer.ingress[0].ip}'
If you overrode defaults and enabled support for an ingress controller, you probably know what you're doing well enough to track down the correct IP without our help. 😉
With this public IP in hand, edit your name servers and add an A
record
pointing your domain to the public IP.
Usage
To use, add the following markdown (with appropriate substitutions where you
see angled brackets) to your README.md
or any other markdown doc needing such
a badge:
![badgr](https://<host name>/v1/github/checks/<user or org name>/<repo name>/badge.svg?branch=<optional branch name>&appID=<optional GitHub App ID>)
Contributing
Badgr is part of the Brigade project and accepts contributions via GitHub pull requests. The Contributing document outlines the process to help get your contribution accepted.
Support & Feedback
We have a slack channel! Kubernetes/#brigade Feel free to join for any support questions or feedback, we are happy to help. To report an issue or to request a feature open an issue here
Code of Conduct
Participation in the Brigade project is governed by the CNCF Code of Conduct.