← Back to plugins index | |
Global configuration and options | |
Supported features → Full specification |
|
👤 Users 👥 Organizations 📓 Repositories |
|
🗝️ token 🗝️ committer_token |
|
➡️ Jump to all available options
By default, dates use Greenwich meridian (GMT/UTC).
Configure config_timezone
(see supported timezone) to avoid time offsets.
Example: configuring timezone
- uses: lowlighter/metrics@latest
with:
config_timezone: Europe/Paris
Content can be manually ordered using config_order
option.
Example: display base.header, isocalendar, languages and stars in this specific order
- uses: lowlighter/metrics@latest
with:
base: header
plugin_isocalendar: yes
plugin_languages: yes
plugin_stars: yes
config_order: base.header, isocalendar, languages, stars
💡 Omitted sections will be appended at the end using default order
ℹ️ The handles to use for each plugin and sections is based on the
partials/_.json
of the template. It may not necessarily be the plugin id (e.g.base.header
,base.activity+community
,base.repositories
, etc.).
Some plugins support a plugin_*_skipped
option which is used to skipped repositories from result. It inherits the global option repositories_skipped
which makes it easier to ignore repositories from all plugins at once.
These options support two different syntaxes:
Skip repositories by:
- using their full handle (e.g.
user/repo
) - using only their name (e.g.
repo
)- in this case, the owner may be implicitly set to current
user
option
- in this case, the owner may be implicitly set to current
Example: skipping repositories with basic pattern matching
repositories_skipped: my-repo, user/my-repo
💡 Either comma or newlines can be used to separate basic patterns
To enable advanced pattern matching to skip repositories, include @use.patterns
at the beginning of the option value.
Skip repositories by writing file-glob patterns, with any of the supported operation:
#
to write comments-
to exclude repositories- the
-
is implicit and may be omitted from excluding patterns
- the
+
to include back repositories
ℹ️ metrics use isaacs/minimatch as its file-glob matcher
Example: skipping repositories with basic advanced matching
repositories_skipped: |
@use.patterns
# Skip a specific repository (both patterns are equivalent)
user/repo
-user/repo
# Skip repositories matching a given pattern
user/repo-*
{user1, user2, user3}/*
# Include back a previously skipped repository
org/repo
+org/include-this-repo
ℹ️ Unlike basic pattern matching, patterns are always tested against the full repository handle (the user will not be implicitly added)
⚠️ As patterns may contain commas, be sure to use newlines rather than commas as separator to ensure patterns are correctly parsed
It is possible to reuse the same configuration across different repositories and workflows using configuration presets. A preset override the default values of inputs, and multiple presets can be provided at once through URLs or file paths.
Options resolution is done in the following order:
- default values
- presets, from first to last
- user values
Example: using a configuration preset from an url
- uses: lowlighter/metrics@latest
with:
config_presets: https://raw.githubusercontent.com/lowlighter/metrics/presets/lunar-red/preset.yaml
Some presets are hosted on this repository on the @presets
branch and can be used directly by using their identifier prefixed by an arobase (@
).
Example: using a pre-defined configuration preset
- uses: lowlighter/metrics@latest
with:
config_presets: "@lunar-red"
⚠️ 🔐 Tokens
and options marked with⏯️ Cannot be preset
, as they suggest, cannot be preset and thus requires to be explicitly defined to be set.
ℹ️ Presets configurations use schemas to ensure compatibility between format changes
Additional CSS can be injected using extras_css
option.
Example: changing the color of h2
- uses: lowlighter/metrics@latest
with:
base: header
extras_css: |
h2 {
color: red;
}
💡 metrics does not use
!important
keyword, so use it when having trouble when styling is not applied
💡 If you make an heavy use of this option, creating a community templates may be a better alternative
⚠️ CSS styles may slightly change between releases, backward compatibility is not guaranteed!
Additional JavaScript can be injected using extras_js
option.
Example: removing all h2
- uses: lowlighter/metrics@latest
with:
base: header
extras_js: |
document.querySelectorAll("h2")?.forEach(h2 => h2.remove())
ℹ️ JavaScript is executed in puppeteer context during the rendering phase, not in metrics context. It will be possible to access
document
and all other features accessible like if the SVG was opened in a browser page
💡 If you make an heavy use of this option, creating a community templates may be a better alternative
⚠️ HTML elements may slightly change between releases, backward compatibility is not guaranteed!
SVG rendering is dependent on operating system, browser and fonts combination and may look different across different platforms.
It may not look like it, but computing the height of a SVG is not trivial. metrics spawns an headless browser and try to do its best to resize the result, but it may sometimes ends up in either cropped or oversized images.
Tweak config_padding
option to manually adjust padding and solve this issue.
This settings supports the following format:
- 1 value for both width and height
- 2 values for width first and height second, separated by a comma (
,
)
💡 Both negative and positive values are allowed
Each value need to respect the following format:
- {number}
- {number} + {number}%
- {number}%
💡 Percentage based values are relative to the height computed by puppeteer
Example: add 10px padding for both width and height
- uses: lowlighter/metrics@latest
with:
config_padding: 10
Example: add 10px padding to height and increase it by 8%
- uses: lowlighter/metrics@latest
with:
config_padding: 0, 10 + 8%
Example: remove 10% from height
- uses: lowlighter/metrics@latest
with:
config_padding: 0, -10%
Some templates may support different output display size.
A regular
display size will render a medium-sized image suitable for both desktop and mobile displays, while a large
one will be more suitable only for desktop and some plugins (like 📌 topics
or 🏅 contributors
)
The columns
display will render a full-width image with automatic resizing: two columns for desktop and a single one column for mobiles.
Example: output a PNG image
- uses: lowlighter/metrics@latest
with:
config_display: large
Use config_output
to change output format.
Example: output a PNG image
- uses: lowlighter/metrics@latest
with:
config_output: png
A JSON output can be used to retrieved collected data and use it elsewhere.
Example: output a JSON data dump
- uses: lowlighter/metrics@latest
with:
config_output: json
When using a PDF output, it is advised to set config_base64: yes
to encode embed images in base64 in order to make self-contained documents.
Example: output a self-contained PDF document
- uses: lowlighter/metrics@latest
with:
markdown: TEMPLATE.md
config_output: markdown-pdf
config_base64: yes
It is possible to generate a self-contained HTML file containing ✨ Metrics insights
output by using config_output: insights
.
💡 Note that like
✨ Metrics insights
content is not configurable, thus any other plugin option will actually be ignored
Example: output ✨ Metrics insights
report
- uses: lowlighter/metrics@latest
with:
config_output: insights
Before configuring output action, ensure that workflows permissions are properly set. These can be changed either through repository settings in Actions tab:
Or more granulary at job or workflow level.
Use output_action: commit
to make the action directly push changes to committer_branch
with a commit.
A custom commit message can be used through committer_message
.
💡 metrics will automatically ignore push events with a commit message containing
[Skip GitHub Action]
orAuto-generated metrics for run #
to avoid infinite loops. Note that by default, GitHub already ignore events pushed by${{ github.token }}
or containing[skip ci]
in commit message
Example: push output to metrics-renders branch rather than the default branch
metrics:
permissions:
contents: write
steps:
- uses: lowlighter/metrics@latest
with:
output_action: commit
committer_branch: metrics-renders
committer_message: "chore: update metrics"
Use output_action: pull-request
to make the action open a new pull request and push changes from the same run on it.
The last step should use either pull-request-merge
, pull-request-squash
or pull-request-rebase
to merge changes to committer_branch
.
💡 When using
pull-request
output action, do not forget to changefilename
too or previous output will be overwritten!
Example: push two outputs using a merge pull request
metrics:
permissions:
contents: write
pull-requests: write
steps:
- uses: lowlighter/metrics@latest
with:
filename: my-metrics-0.svg
output_action: pull-request
- uses: lowlighter/metrics@latest
with:
filename: my-metrics-1.svg
output_action: pull-request-merge
Use output_action: gist
to push output to a GitHub gist instead.
It is required to provide a gist id to committer_gist
option to make it work.
💡 This feature will use
token
instead ofcommitter_token
to push changes, sogists
scope must be granted to the originaltoken
first
Example: push output to a gist
metrics:
steps:
- uses: lowlighter/metrics@latest
with:
output_action: gist
committer_gist: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Use output_action: none
to perform custom processing with outputs.
They will be available under /metrics_renders/{filename}
in the runner.
Example: generate outputs and manually push them
metrics:
permissions:
contents: write
steps:
- name: Checkout repository
uses: actions/checkout@v3
with:
fetch-depth: 0
- uses: lowlighter/metrics@latest
with:
output_action: none
- uses: lowlighter/metrics@latest
run: |
set +e
git checkout metrics-renders
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
sudo mv /metrics_renders/* ./
git add --all
git commit -m "chore: push metrics"
git push
Rendering is subject to external factors and can fail occasionally.
Use retries
and retries_delay
options to automatically retry rendering.
Example: retry render up to 3 times (wait 5 minutes between each fail)
- uses: lowlighter/metrics@latest
with:
retries: 3
retries_delay: 300
Output action is also subject to GitHub API rate-limiting and overall health status and can fail occasionally.
Use retries_output_action
and retries_delay_output_action
options to automatically retry output action.
💡 As output action is a separate step from rendering, render step won't be called again
Example: retry output action up to 5 times (wait 2 minutes between each fail)
- uses: lowlighter/metrics@latest
with:
retries_output_action: 5
retries_delay_output_action: 120
To reduce filesize and decrease loading time, metrics offers several optimization options, such as purging unused CSS and style minification, XML pretty-printing (which also reduce diffs between changes) and general SVG optimization (still experimental).
💡 This option is enabled by default!
Example: optimize CSS and XML
- uses: lowlighter/metrics@latest
with:
optimize: css, xml
Example: optimize SVG (experimental)
- uses: lowlighter/metrics@latest
with:
optimize: svg
experimental_features: --optimize-svg
When using lowlighter/metrics
official releases as a GitHub Action, a prebuilt docker container image will be pulled from GitHub Container Registry. It allows to significantly reduce workflow execution time.
💡 This option is enabled by default!
On forks, this feature is disable to take into account any changes you made on it.
Example: using prebuilt docker image
- uses: lowlighter/metrics@latest
with:
use_prebuilt_image: yes
Option | Description |
GitHub Personal Access Token No scopes are required by default, though some plugins and features may require additional scopes. When using a configuration which does not requires a GitHub PAT, it is possible to pass |
|
✔️ Required 🔐 Token type: token
|
|
GitHub username Defaults to |
|
⏯️ Cannot be preset type: string
|
|
GitHub repository This option is only revelant for repositories templates |
|
⏯️ Cannot be preset type: string
|
|
GitHub Token used to commit metrics Leave this to
|
|
🔐 Token type: token
default: ${{ github.token }} |
|
Target branch Defaults to current repository default branch |
|
type: string
|
|
Commit message Use |
|
type: string
default: Update ${filename} - [Skip GitHub Action] |
|
Gist id Specify an existing gist id (can be retrieved from its URL) when using |
|
⏯️ Cannot be preset type: string
|
|
Output path When using an asterisk ( |
|
type: string
default: github-metrics.* |
|
Markdown template path It can be either a local path or a full link (e.g. https://raw.githubusercontent.com) |
|
type: string
default: TEMPLATE.md |
|
Markdown file cache |
|
type: string
default: .cache |
|
Output action
|
|
type: string
default: commit allowed values:
|
|
Output condition
|
|
type: string
default: always allowed values:
|
|
Optimization features
Templates may not always honour all provided options |
|
type: array
(comma-separated)
default: css, xml allowed values:
|
|
Community templates to setup See community templates guide for more informations |
|
🌐 Web instances must configure settings.json :
array
(comma-separated)
|
|
Template Community templates must be prefixed by at sign ( |
|
type: string
default: classic |
|
Query parameters Pass additional parameters to templates. This is mostly useful for custom templates.
|
|
type: json
default: → Click to expand
|
|
Extra CSS Custom CSS that will be injected in used template. Useful to avoid creating a new template just to tweak some styling
|
|
🌐 Web instances must configure settings.json :
string
|
|
Extra JavaScript Custom JavaScript that will be executed during puppeteer rendering. Useful to avoid creating a new template just to tweak some content.
|
|
🌐 Web instances must configure settings.json :
string
|
|
GitHub REST API endpoint Can be used to support GitHub enterprises server. Leave empty to use default endpoint. |
|
⏭️ Global option type: string
|
|
GitHub GraphQL API endpoint Can be used to support GitHub enterprises server. Leave empty to use default endpoint.
|
|
⏭️ Global option type: string
|
|
Timezone for dates See list of supported timezone |
|
⏭️ Global option type: string
|
|
Plugin order By default, templates use If some partials are omitted, they will be appended at the end with default ordering |
|
⏭️ Global option type: array
(comma-separated)
|
|
Use twemojis Replace emojis by twemojis to have a consistent render across all platforms May increase filesize. |
|
⏭️ Global option type: boolean
default: no |
|
Use GitHub custom emojis GitHub supports additional emojis which are not registered in Unicode standard (:octocat:, :shipit:, :trollface:, ...) See full list at https://api.github.com/emojis. This option has no effect when [`token: NOT_NEEDED``](/source/plugins/core/README.md#token) is set. May increase filesize |
|
⏭️ Global option type: boolean
default: yes |
|
Use GitHub octicons Octicons are open-sourced icons provided by GitHub. See full list at https://primer.style/octicons. To include an octicon, use the following syntax: May increase filesize |
|
⏭️ Global option type: boolean
default: no |
|
Display width (for image output formats)
|
|
⏭️ Global option type: string
default: regular allowed values:
|
|
Use CSS animations |
|
⏭️ Global option type: boolean
default: yes |
|
Base64-encoded images Enable this option to make self-contained output (i.e. with no external links) |
|
⏭️ Global option type: boolean
default: yes |
|
Output padding Although metrics try to auto-guess resulting height, rendering is still dependent on OS and browser settings. It can result in cropped or oversized outputs. This settings let you manually adjust padding with the following format:
Each value need to respect the following format:
Percentage are relative to computed dimensions |
|
type: string
default: 0, 8 + 11% |
|
Output format
|
|
type: string
default: auto allowed values:
|
|
Configuration presets |
|
⏯️ Cannot be preset 🌐 Web instances must configure settings.json :
array
(comma-separated)
|
|
Retries in case of failures (for rendering) |
|
type: number
(1 ≤
𝑥
≤ 10)
default: 3 |
|
Delay between each retry (in seconds, for rendering) |
|
type: number
(0 ≤
𝑥
≤ 3600)
default: 300 |
|
Retries in case of failures (for output action) |
|
type: number
(1 ≤
𝑥
≤ 10)
default: 5 |
|
Delay between each retry (in seconds, for output action) |
|
type: number
(0 ≤
𝑥
≤ 3600)
default: 120 |
|
Clean previous workflows jobs This can be used to clean up Action tabs from previous workflows runs. Use
|
|
⏯️ Cannot be preset type: array
(comma-separated)
allowed values:
|
|
Job delay This can be used to avoid triggering GitHub abuse mechanics on large workflows |
|
type: number
(0 ≤
𝑥
≤ 3600)
default: 0 |
|
Minimum GitHub REST API requests quota required to run Action will cancel itself without any errors if requirements are not met This option has no effect when |
|
type: number
(0 ≤
𝑥
≤ 5000)
default: 200 |
|
Minimum GitHub GraphQL API requests quota required to run Action will cancel itself without any errors if requirements are not met This option has no effect when |
|
type: number
(0 ≤
𝑥
≤ 5000)
default: 200 |
|
Minimum GitHub Search API requests quota required to run Action will cancel itself without any errors if requirements are not met This option has no effect when |
|
type: number
(0 ≤
𝑥
≤ 30)
default: 0 |
|
Notice about new releases of metrics |
|
type: boolean
default: yes |
|
Use pre-built docker image from GitHub container registry It allows to save build time and make job significantly faster, and there is almost no reason to disable this settings. This option has no effects on forks (images will always be rebuilt from Dockerfile) |
|
⏯️ Cannot be preset 🔧 For development type: boolean
default: yes |
|
Fatal plugin errors When enabled, the job will fail in case of plugin errors, else it will be handled gracefully in output with an error message |
|
⏯️ Cannot be preset 🔧 For development type: boolean
default: no |
|
Debug mode This setting is automatically enable if a job fail (useful with |
|
⏯️ Cannot be preset 🔧 For development type: boolean
default: no |
|
SVG validity check |
|
⏯️ Cannot be preset 🔧 For development 🌐 Web instances must configure settings.json :
boolean
default: no |
|
Debug flags
|
|
⏯️ Cannot be preset 🔧 For development type: array
(space-separated)
allowed values:
|
|
Print output in console |
|
⏯️ Cannot be preset 🔧 For development type: boolean
default: no |
|
Dry-run
|
|
⏯️ Cannot be preset 🔧 For development type: boolean
default: no |
|
Experimental features
|
|
⏯️ Cannot be preset 🔧 For development type: array
(space-separated)
allowed values:
|
|
Use mocked data instead of live APIs |
|
⏯️ Cannot be preset 🔧 For development type: boolean
default: no |