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:
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 v1.1.1 > ~/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.
-
service.type
: If you plan to enable ingress (advanced), you can leave this
as its default -- ClusterIP
. If you do not plan to enable ingress, you
probably will want to change this value to LoadBalancer
.
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 v1.1.1 \
--create-namespace \
--namespace badgr \
--values ~/badgr-values.yaml \
--wait \
--timeout 300s
2. (RECOMMENDED) Create a DNS Entry
If you overrode defaults and set service.type
to LoadBalancer
, use this
command to 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.