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!
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 to a gist (click here for an example) and automatically transformed to 
Show Markdown of this Badge!
The action also supports an SVG mode in which the badge is created directly by the action and uploaded as image to the gist.
This mode does not support all features of shields.io but is useful if you cannot use shields.io for some reason.
which is directly stored in a gist.
Show Markdown of this Badge!
Both, JSON and SVG mode support emoji in the label and message.
However, this is especially great in SVG mode which does not support icons. Here's an SVG emoji badge which does not use shields.io at all: .
- 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. - Navigate to github.com/settings/tokens and create a new token with the gist scope.
- 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). - Add something like the following to your workflow:
- name: Create Awesome Badge
uses: schneegans/dynamic-badges-action@v1.7.0
with:
auth: ${{ secrets.GIST_SECRET }}
gistID: <gist-ID>
filename: test.json # Use test.svg if you want to use the SVG mode.
label: Hello
message: World
color: orangeOnce the action is executed, go to your gist.
There should be a new file called test.json (or test.svg if you used SVG mode).
Embed the badge with:
| Parameter | Description |
|---|---|
auth |
A secret token with the gist scope. |
gistID |
The ID of the target gist. Something like 8f6459c2417de7534f64d98360dde866. |
filename |
The target filename - each gist may contain several files. This should have a .json extension if you want to use shields.io/endpoint or an .svg extension if you want to use the SVG mode described above. |
| Parameter | Description | Supported in SVG Mode |
|---|---|---|
host |
Default is https://api.github.com/gists/. You can change this if you're using GitHub enterprise. The URL will be something like https://github-enterprise-hostname/api/v3/gists/. |
✅ |
forceUpdate |
Default is false. If set to true, the gist will be updated even if the content did not change. |
✅ |
All these parameters are optional. They are directly passed to shields.io. See the official documentation for more detailed explanations.
| Parameter | Description | Supported in SVG Mode |
|---|---|---|
label |
Required. The left text of the badge. | ✅ |
message |
Required. The right text of the badge. | ✅ |
labelColor |
The left color of the badge. | ✅ |
color |
The right color of the badge. For custom colors wrap color string in quotes "#bf155b". This parameter is ignored if the valColorRange, maxColorRange, and minColorRange are set. |
✅ |
isError |
The color will be red and cannot be overridden. | |
namedLogo |
A logo name from simpleicons.org. | |
logoSvg |
An svg-string to be used as logo. | |
logoColor |
The color for the logo. | |
logoWidth |
The space allocated for the logo. | |
logoPosition |
The position of the logo. | |
style |
The style like "flat" or "social". | ✅ |
cacheSeconds |
The cache lifetime in seconds (must be greater than 300). |
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.
| Parameter | Description | Supported in SVG Mode |
|---|---|---|
valColorRange |
A numerical value used to define the message color. Usually this should be between maxColorRange and minColorRange. This is required if you want to use the color range feature. |
✅ |
maxColorRange |
If valColorRange assumes this value, the badge will be green. This is required if you want to use the color range feature. |
✅ |
minColorRange |
If valColorRange assumes this value, the badge will be red. This is required if you want to use the color range feature. |
✅ |
invertColorRange |
If the range should be inverted, causing a smaller value to have green color. Defaults to false. |
✅ |
colorRangeSaturation |
Saturation used by the color range feature. Defaults to 100. | ✅ |
colorRangeLightness |
Lightness used by the color range feature. Defaults to 40. | ✅ |
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/dynamic-badges-action@v1.7.0
with:
auth: ${{ secrets.GIST_SECRET }}
gistID: <gist-ID>
filename: answer.json
label: The Answer
message: is ${{ env.ANSWER }}
valColorRange: ${{ env.ANSWER }}
maxColorRange: 100
minColorRange: 0The current action is compatible with node20 only. In order to use it with a self-hosted runner, you must use runner with node20 installed. Your runner version must be equal or higher than v2.308.0.
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.
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!
| Emoji | Description |
|---|---|
🎉 :tada: |
When you added a cool new feature. |
🔧 :wrench: |
When you refactored / improved a small piece of code. |
🔨 :hammer: |
When you refactored / improved large parts of the code. |
✨ :sparkles: |
When you applied clang-format. |
🎨 :art: |
When you improved / added assets like themes. |
🚀 :rocket: |
When you improved performance. |
📝 :memo: |
When you wrote documentation. |
🪲 :beetle: |
When you fixed a bug. |
🔀 :twisted_rightwards_arrows: |
When you merged a branch. |
🔥 :fire: |
When you removed something. |
🚚 :truck: |
When you moved / renamed something. |
Version numbers will be assigned according to the Semantic Versioning scheme. This means, given a version number MAJOR.MINOR.PATCH, we will increment the:
- MAJOR version when we make incompatible API changes,
- MINOR version when we add functionality in a backwards compatible manner, and
- PATCH version when we make backwards compatible bug fixes.