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 and helm (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 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.