Dynamic Badges Action

This action allows you to create badges for your README.md with shields.io which may change with every commit. To do this, this action does not need to push anything to your repository!

This action supports all configuration options of shields.io/endpoint and can be used in various ways:

• Show custom CI statistics from GitHub actions, such as code coverage or detailed test results.
• Show metadata of your repository such as lines of code, comment line percentage, ...
• Basically anything which may change from commit to commit!

How Does It Work?

Whenever this action is executed, it creates a JSON object based on the input parameters. This JSON object may look like this:

{
  "schemaVersion": 1,
  "label": "Hello",
  "message": "World",
  "color": "orange"
}

This JSON object is then uploaded as a file to a gist (click here for an example) and can be transformed to a badge like with the shields.io/endpoint. Here is the URL of this example badge:

https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/hello-world.json

Configuration

1. Head over to gist.github.com and create a new gist. You can name the file test.json, but this can be changed later as well. You will need the ID of the gist (this is the long alphanumerical part of its URL) later.
2. Navigate to github.com/settings/tokens and create a new token with the gist scope.
3. Go to the Secrets page of the settings of your repository (Settings > Secrets > Actions) and add this token as a new secret. You can give it any name, for example GIST_SECRET. If you use Dependabot to automatically update dependencies of your repository, you also have to add this secret to Dependabot's secrets (Settings > Secrets > Dependabot).
4. Add something like the following to your workflow:

- name: Create Awesome Badge
  uses: schneegans/[email protected]
  with:
    auth: ${{ secrets.GIST_SECRET }}
    gistID: <gist-ID>
    filename: test.json
    label: Hello
    message: World
    color: orange

Once the action is executed, go to your gist. There should be a new file called test.json. You can view the raw content of this file at https://gist.githubusercontent.com/<user>/<gist-ID>/raw/test.json. Embed the badge with:

![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/<user>/<gist-ID>/raw/test.json)

Required Input Parameters

Optional Input Parameters

Shields.io Parameters (optional)

All these parameters are optional. They are directly passed to shields.io. See the official documentation for more detailed explanations.

Color Range Parameters (optional)

Starting with version 1.3.0 of this action, the color of the right side of the badge can be computed automatically on a green-to-red color-scale. For example, these badges have been colored with minColorRange: 50 and maxColorRange: 90:

For this, the following parameters can be used.

Using Environment Variables as Parameters

A common usage pattern of this action is to create environment variables in previous steps of a job and later use them as message in your badge. How this can be done, is shown in the following example.

This example also shows how to use the automatic color range feature: If the answer is <= 0, the badge will be red, if it's >= 100 it will be green. For all values in between, the color will be interpolated.

- name: Get the Numbers
  run: echo "ANSWER=42" >> $GITHUB_ENV
- name: Create the Badge
  uses: schneegans/[email protected]
  with:
    auth: ${{ secrets.GIST_SECRET }}
    gistID: <gist-ID>
    filename: answer.json
    label: The Answer
    message: is ${{ env.ANSWER }}
    valColorRange: ${{ env.ANSWER }}
    maxColorRange: 100
    minColorRange: 0

Contributing to Dynamic Badges Action

Whenever you encounter a 🪲 bug or have 🎉 feature request, report this via Github issues.

We are happy to receive contributions in the form of pull requests via Github. Feel free to fork the repository, implement your changes and create a merge request to the master branch.

Git Commit Messages

Commits should start with a Capital letter and should be written in present tense (e.g. 🎉 Add cool new feature instead of 🎉 Added cool new feature). You should also start your commit message with one applicable emoji. This does not only look great but also makes you rethink what to add to a commit. Make many but small commits!

Version Numbers

Version numbers will be assigned according to the Semantic Versioning scheme. This means, given a version number MAJOR.MINOR.PATCH, we will increment the:

1. MAJOR version when we make incompatible API changes,
2. MINOR version when we add functionality in a backwards compatible manner, and
3. PATCH version when we make backwards compatible bug fixes.