← Back to plugins index

🧱 Core

Global configuration and options

Supported features
→ Full specification
👤 Users đŸ‘Ĩ Organizations 📓 Repositories
🗝ī¸ token 🗝ī¸ committer_token
[➡ī¸ Jump to all available options](#%EF%B8%8F-available-options) ## 🌐 Configure used timezone By default, dates use Greenwich meridian (GMT/UTC). Configure `config_timezone` (see [supported timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) to avoid time offsets. *Example: configuring timezone* ```yaml - uses: lowlighter/metrics@latest with: config_timezone: Europe/Paris ``` ## đŸ“Ļ Ordering content Content can be manually ordered using `config_order` option. *Example: display base.header, isocalendar, languages and stars in this specific order* ```yaml - 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`](/source/templates/classic/partials/_.json) of the template. > It may not necessarily be the plugin id (e.g. `base.header`, `base.activity+community`, `base.repositories`, etc.). ## 🔕 Skipping repositories in plugins Some plugins support a `plugin_*_skipped` option which is used to skipped repositories from result. It inherits the global option [`repositories_skipped`](/source/plugins/base/README.md#repositories_skipped) which makes it easier to ignore repositories from all plugins at once. These options support two different syntaxes: ### Basic pattern matching 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* *Example: skipping repositories with basic pattern matching* ```yml repositories_skipped: my-repo, user/my-repo ``` > 💡 Either comma or newlines can be used to separate basic patterns ### Advanced pattern matching 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* - `+` to include back repositories > ℹī¸ *metrics* use [isaacs/minimatch](https://github.com/isaacs/minimatch) as its file-glob matcher *Example: skipping repositories with basic advanced matching* ```yml 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 ## đŸĒ› Using presets 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* ```yaml - 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`](https://github.com/lowlighter/metrics/tree/presets) branch and can be used directly by using their identifier prefixed by an arobase (`@`). *Example: using a pre-defined configuration preset* ```yaml - 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](https://github.com/lowlighter/metrics/tree/presets/%40schema) to ensure compatibility between format changes ## 🎨 Custom CSS styling Additional CSS can be injected using `extras_css` option. *Example: changing the color of `h2`* ```yaml - 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](/source/templates/community/README.md) may be a better alternative > ⚠ī¸ CSS styles may slightly change between releases, backward compatibility is not guaranteed! ## đŸ—ŗī¸ Custom JavaScript scripting Additional JavaScript can be injected using `extras_js` option. *Example: removing all `h2`* ```yaml - 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](/source/templates/community/README.md) may be a better alternative > ⚠ī¸ HTML elements may slightly change between releases, backward compatibility is not guaranteed! ## 🔲 Adjusting padding 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* ```yaml - uses: lowlighter/metrics@latest with: config_padding: 10 ``` *Example: add 10px padding to height and increase it by 8%* ```yaml - uses: lowlighter/metrics@latest with: config_padding: 0, 10 + 8% ``` *Example: remove 10% from height* ```yaml - uses: lowlighter/metrics@latest with: config_padding: 0, -10% ``` ## ↔ī¸ Controlling display size 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`](/source/plugins/topics/README.md) or [`🏅 contributors`](/source/plugins/contributors/README.md)) 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* ```yaml - uses: lowlighter/metrics@latest with: config_display: large ``` ## 💱 Configuring output format Use `config_output` to change output format. *Example: output a PNG image* ```yaml - 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* ```yaml - 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* ```yaml - uses: lowlighter/metrics@latest with: markdown: TEMPLATE.md config_output: markdown-pdf config_base64: yes ``` ## ✨ Render `Metrics insights` statically 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* ```yaml - uses: lowlighter/metrics@latest with: config_output: insights ``` ## đŸ§ļ Configuring output action Before configuring output action, ensure that workflows permissions are properly set. These can be changed either through repository settings in Actions tab: ![Setting workflows permissions](/.github/readme/imgs/setup_workflow_permissions.light.png#gh-light-mode-only) ![Setting workflows permissions](/.github/readme/imgs/setup_workflow_permissions.dark.png#gh-dark-mode-only) Or more granulary [at job or workflow level](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). ### Using commits (default) 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]` or `Auto-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* ```yaml metrics: permissions: contents: write steps: - uses: lowlighter/metrics@latest with: output_action: commit committer_branch: metrics-renders committer_message: "chore: update metrics" ``` ### Using pull requests 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 change `filename` too or previous output will be overwritten! *Example: push two outputs using a merge pull request* ```yaml 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 ``` ### Using gists Use `output_action: gist` to push output to a [GitHub gist](https://gist.github.com) instead. It is required to provide a gist id to `committer_gist` option to make it work. > 💡 This feature will use `token` instead of `committer_token` to push changes, so `gists` scope must be granted to the original `token` first *Example: push output to a gist* ```yaml metrics: steps: - uses: lowlighter/metrics@latest with: output_action: gist committer_gist: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ### Manual handling 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* ```yaml 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 ``` ## â™ģī¸ Retrying automatically failed rendering and output action 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)* ```yaml - 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)* ```yaml - uses: lowlighter/metrics@latest with: retries_output_action: 5 retries_delay_output_action: 120 ``` ## 🗜ī¸ Optimize SVG output 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* ```yaml - uses: lowlighter/metrics@latest with: optimize: css, xml ``` *Example: optimize SVG (experimental)* ```yaml - uses: lowlighter/metrics@latest with: optimize: svg experimental_features: --optimize-svg ``` ## đŸŗ Faster execution with prebuilt docker images When using `lowlighter/metrics` official releases as a GitHub Action, a prebuilt docker container image will be pulled from [GitHub Container Registry](https://github.com/users/lowlighter/packages/container/package/metrics). 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* ```yaml - uses: lowlighter/metrics@latest with: use_prebuilt_image: yes ``` ## ➡ī¸ Available options
OptionDescription

token

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 NOT_NEEDED instead. When doing so, any settings which defaults on user fetched values will not be templated (e.g. .user.*) and will usually need to be set manually.
✔ī¸ Required
🔐 Token
type: token

user

GitHub username

Defaults to token owner username.
⏯ī¸ Cannot be preset
type: string

repo

GitHub repository

This option is only revelant for repositories templates
⏯ī¸ Cannot be preset
type: string

committer_token

GitHub Token used to commit metrics

Leave this to ${{ github.token }} or ${{ secrets.GITHUB_TOKEN }}, which is a special auto-generated token restricted to current repository scope.

💡 When using output_action: gist, it will use token instead, since gists are outside of scope
🔐 Token
type: token
default: ${{ github.token }}

committer_branch

Target branch

Defaults to current repository default branch
type: string

committer_message

Commit message

Use ${filename} to display filename
type: string
default: Update ${filename} - [Skip GitHub Action]

committer_gist

Gist id

Specify an existing gist id (can be retrieved from its URL) when using output_action: gist.
⏯ī¸ Cannot be preset
type: string

filename

Output path

When using an asterisk (*), correct extension will automatically be applied according to config_output value
type: string
default: github-metrics.*

markdown

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_cache

Markdown file cache
type: string
default: .cache

output_action

Output action

  • none: just create file in /metrics_renders directory of action runner
  • commit: push output to committer_branch
  • pull-request: push output to a new branch and open a pull request to committer_branch
  • pull-request-merge: same as pull-request and additionally merge pull request
  • pull-request-squash: same as pull-request and additionally squash and merge pull request
  • pull-request-rebase: same as pull-request and additionally rebase and merge pull request
  • gist: push output to committer_gist

💡 When using pull-request, you will need to set the last job with a pull-request-* action instead, else it won't be merged

⚠ī¸ As GitHub gists API does not support binary files upload, gist does not support config_output set to either png, jpeg or markdown-pdf
type: string
default: commit
allowed values:
  • none
  • commit
  • pull-request
  • pull-request-merge
  • pull-request-squash
  • pull-request-rebase
  • gist

output_condition

Output condition

  • always: always try to push changes
  • data-changed: skip changes if no data changed (e.g. like when only metadata changed)

ℹī¸ This option is only revelant when config_output: svg is set
type: string
default: always
allowed values:
  • always
  • data-changed

optimize

Optimization features

Templates may not always honour all provided options
type: array (comma-separated)
default: css, xml
allowed values:
  • css
  • xml
  • svg

setup_community_templates

Community templates to setup

See community templates guide for more informations
🌐 Web instances must configure settings.json:
  • metrics.setup.community.templates
type: array (comma-separated)

template

Template

Community templates must be prefixed by at sign (@) See list of supported templates
type: string
default: classic

query

Query parameters

Pass additional parameters to templates. This is mostly useful for custom templates.

⚠ī¸ Do not use this option to pass other existing parameters, they will be overwritten
type: json
default:
→ Click to expand
{}

extras_css

Extra CSS

Custom CSS that will be injected in used template. Useful to avoid creating a new template just to tweak some styling

💡 metrics tends to avoid using !important rules, which means that most styling can be overridden by this option when using !important
🌐 Web instances must configure settings.json:
  • metrics.run.puppeteer.user.css
type: string

extras_js

Extra JavaScript

Custom JavaScript that will be executed during puppeteer rendering. Useful to avoid creating a new template just to tweak some content.

⚠ī¸ Note that is it executed within puppeteer context and not within metrics context. No access to fetched data or configuration will be offered through this context. It is run after transformations and optimizations, but just before resizing.
🌐 Web instances must configure settings.json:
  • metrics.run.puppeteer.user.js
type: string

github_api_rest

GitHub REST API endpoint

Can be used to support GitHub enterprises server. Leave empty to use default endpoint.
⏭ī¸ Global option
type: string

github_api_graphql

GitHub GraphQL API endpoint

Can be used to support GitHub enterprises server. Leave empty to use default endpoint.

ℹī¸ GraphQL octokit will automatically append /graphql to provided endpoint
⏭ī¸ Global option
type: string

config_timezone

Timezone for dates

See list of supported timezone
⏭ī¸ Global option
type: string

config_order

Plugin order

By default, templates use partials/_.json ordering. You can override the content order by using this setting.

If some partials are omitted, they will be appended at the end with default ordering
⏭ī¸ Global option
type: array (comma-separated)

config_twemoji

Use twemojis

Replace emojis by twemojis to have a consistent render across all platforms May increase filesize.
⏭ī¸ Global option
type: boolean
default: no

config_gemoji

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

config_octicon

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: :octicon-{name}-{size}:. Size must be a supported icon size (12, 16 or 24). 16px octicons can omit size and directly use :octicon-{name}: syntax.

May increase filesize
⏭ī¸ Global option
type: boolean
default: no

config_display

Display width (for image output formats)
⏭ī¸ Global option
type: string
default: regular
allowed values:
  • regular
  • large
  • columns

config_animations

Use CSS animations
⏭ī¸ Global option
type: boolean
default: yes

config_base64

Base64-encoded images

Enable this option to make self-contained output (i.e. with no external links)
⏭ī¸ Global option
type: boolean
default: yes

config_padding

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:

  • 1 value for both width and height
  • 2 values for width fist and height second, separated by a comma (,)

Each value need to respect the following format:

  • {number}
  • {number} + {number}%
  • {number}%

Percentage are relative to computed dimensions
type: string
default: 0, 8 + 11%

config_output

Output format

  • auto: Template default (usually svg or markdown)
  • svg: SVG image
  • png: PNG image (animations not supported)
  • jpeg: JPEG image (animations and transparency not supported)
  • json: JSON data dump
  • markdown: Markdown rendered file
  • markdown-pdf: PDF from markdown rendered file
  • insights: Metrics Insights self-contained HTML file (not configurable)
type: string
default: auto
allowed values:
  • auto
  • svg
  • png
  • jpeg
  • json
  • markdown
  • markdown-pdf
  • insights

config_presets

Configuration presets
⏯ī¸ Cannot be preset
🌐 Web instances must configure settings.json:
  • metrics.setup.community.presets
type: array (comma-separated)

retries

Retries in case of failures (for rendering)
type: number (1 ≤ đ‘Ĩ ≤ 10)
default: 3

retries_delay

Delay between each retry (in seconds, for rendering)
type: number (0 ≤ đ‘Ĩ ≤ 3600)
default: 300

retries_output_action

Retries in case of failures (for output action)
type: number (1 ≤ đ‘Ĩ ≤ 10)
default: 5

retries_delay_output_action

Delay between each retry (in seconds, for output action)
type: number (0 ≤ đ‘Ĩ ≤ 3600)
default: 120

clean_workflows

Clean previous workflows jobs

This can be used to clean up Action tabs from previous workflows runs.

Use all to clean up workflows runs in any state.

⚠ī¸ When reporting issues, it is required to provide logs so it can be investigated and reproduced. Be sure to disable this option when asking for help or submitting bug reports.
⏯ī¸ Cannot be preset
type: array (comma-separated)
allowed values:
  • cancelled
  • failure
  • success
  • skipped
  • startup_failure
  • timed_out
  • all

delay

Job delay

This can be used to avoid triggering GitHub abuse mechanics on large workflows
type: number (0 ≤ đ‘Ĩ ≤ 3600)
default: 0

quota_required_rest

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 token: NOT_NEEDED is set
type: number (0 ≤ đ‘Ĩ ≤ 5000)
default: 200

quota_required_graphql

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 token: NOT_NEEDED is set
type: number (0 ≤ đ‘Ĩ ≤ 5000)
default: 200

quota_required_search

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 token: NOT_NEEDED is set
type: number (0 ≤ đ‘Ĩ ≤ 30)
default: 0

notice_releases

Notice about new releases of metrics
type: boolean
default: yes

use_prebuilt_image

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

plugins_errors_fatal

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

Debug mode

This setting is automatically enable if a job fail (useful with plugins_errors_fatal: yes)
⏯ī¸ Cannot be preset
🔧 For development
type: boolean
default: no

verify

SVG validity check
⏯ī¸ Cannot be preset
🔧 For development
🌐 Web instances must configure settings.json:
  • metrics.npm.optional.libxml2
type: boolean
default: no

debug_flags

Debug flags

  • --cakeday: simulate registration anniversary
  • --halloween: enable halloween colors
  • --error: force render error
⏯ī¸ Cannot be preset
🔧 For development
type: array (space-separated)
allowed values:
  • --cakeday
  • --halloween
  • --error

debug_print

Print output in console
⏯ī¸ Cannot be preset
🔧 For development
type: boolean
default: no

dryrun

Dry-run

⚠ī¸ Unlike output_action: none, output file won't be available in /metrics_renders directory
⏯ī¸ Cannot be preset
🔧 For development
type: boolean
default: no

experimental_features

Experimental features

⚠ī¸ No backward compatibility is guaranteed for these features
⏯ī¸ Cannot be preset
🔧 For development
type: array (space-separated)
allowed values:
  • --optimize-svg

use_mocked_data

Use mocked data instead of live APIs
⏯ī¸ Cannot be preset
🔧 For development
type: boolean
default: no