ContextQMD
Back to Metrics

README

source/plugins/core/README.md

3.3442.6 KB
Original Source
<!--header--> <table> <tr><td colspan="2"><a href="/README.md#-plugins">← Back to plugins index</a></td></tr> <tr><th colspan="2"><h3>🧱 Core</h3></th></tr> <tr><td colspan="2" align="center"><p>Global configuration and options</p> </td></tr> <tr> <th rowspan="3">Supported features <sub><a href="metadata.yml">→ Full specification</a></sub></th> <td></td> </tr> <tr> <td><code>👤 Users</code> <code>đŸ‘Ĩ Organizations</code> <code>📓 Repositories</code></td> </tr> <tr> <td><code>🗝ī¸ token</code> <code>🗝ī¸ committer_token</code></td> </tr> <tr> <td colspan="2" align="center"> 
</td>
</tr> </table> <!--/header-->

➡ī¸ Jump to all available options

🌐 Configure used timezone

By default, dates use Greenwich meridian (GMT/UTC).

Configure config_timezone (see supported timezone) 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 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 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 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 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 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 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 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 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

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:

Or more granulary at job or workflow level.

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 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. 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

<!--options--> <table> <tr> <td align="center" nowrap="nowrap">Option</i></td><td align="center" nowrap="nowrap">Description</td> </tr> <tr> <td nowrap="nowrap"><h4><code>token</code></h4></td> <td rowspan="2"><p>GitHub Personal Access Token</p> <p>No scopes are required by default, though some plugins and features may require additional scopes.</p> <p>When using a configuration which does not requires a GitHub PAT, it is possible to pass <code>NOT_NEEDED</code> instead. When doing so, any settings which defaults on user fetched values will not be templated (e.g. <code>.user.*</code>) and will usually need to be set manually.</p> </td> </tr> <tr> <td nowrap="nowrap">✔ī¸ Required

🔐 Token

<b>type:</b> <code>token</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>user</code></h4></td> <td rowspan="2"><p>GitHub username</p> <p>Defaults to <a href="/source/plugins/core/README.md#token"><code>token</code></a> owner username.</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

<b>type:</b> <code>string</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>repo</code></h4></td> <td rowspan="2"><p>GitHub repository</p> <p>This option is only revelant for repositories templates</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

<b>type:</b> <code>string</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>committer_token</code></h4></td> <td rowspan="2"><p>GitHub Token used to commit metrics</p> <p>Leave this to <code>${{ github.token }}</code> or <code>${{ secrets.GITHUB_TOKEN }}</code>, which is a special auto-generated token restricted to current repository scope.</p> <blockquote> <p>💡 When using <a href="/source/plugins/core/README.md#output_action"><code>output_action: gist</code></a>, it will use <a href="/source/plugins/core/README.md#token"><code>token</code></a> instead, since gists are outside of scope</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">🔐 Token

<b>type:</b> <code>token</code>

<b>default:</b> ${{ github.token }}

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>committer_branch</code></h4></td> <td rowspan="2"><p>Target branch</p> <p>Defaults to current repository default branch</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code> </td> </tr> <tr> <td nowrap="nowrap"><h4><code>committer_message</code></h4></td> <td rowspan="2"><p>Commit message</p> <p>Use <code>${filename}</code> to display filename</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> Update ${filename} - [Skip GitHub Action]

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>committer_gist</code></h4></td> <td rowspan="2"><p>Gist id</p> <p>Specify an existing gist id (can be retrieved from its URL) when using <a href="/source/plugins/core/README.md#output_action"><code>output_action: gist</code></a>.</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

<b>type:</b> <code>string</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>filename</code></h4></td> <td rowspan="2"><p>Output path</p> <p>When using an asterisk (<code>*</code>), correct extension will automatically be applied according to <a href="/source/plugins/core/README.md#config_output"><code>config_output</code></a> value</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> github-metrics.*

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>markdown</code></h4></td> <td rowspan="2"><p>Markdown template path</p> <p>It can be either a local path or a full link (e.g. <a href="https://raw.githubusercontent.com">https://raw.githubusercontent.com</a>)</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> TEMPLATE.md

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>markdown_cache</code></h4></td> <td rowspan="2"><p>Markdown file cache</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> .cache

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>output_action</code></h4></td> <td rowspan="2"><p>Output action</p> <ul> <li><code>none</code>: just create file in <code>/metrics_renders</code> directory of action runner</li> <li><code>commit</code>: push output to <code>committer_branch</code></li> <li><code>pull-request</code>: push output to a new branch and open a pull request to <code>committer_branch</code></li> <li><code>pull-request-merge</code>: same as <code>pull-request</code> and additionally merge pull request</li> <li><code>pull-request-squash</code>: same as <code>pull-request</code> and additionally squash and merge pull request</li> <li><code>pull-request-rebase</code>: same as <code>pull-request</code> and additionally rebase and merge pull request</li> <li><code>gist</code>: push output to <code>committer_gist</code></li> </ul> <blockquote> <p>💡 When using <code>pull-request</code>, you will need to set the last job with a <code>pull-request-*</code> action instead, else it won&#39;t be merged</p> </blockquote> <blockquote> <p>⚠ī¸ As GitHub gists API does not support binary files upload, <code>gist</code> does not support <a href="/source/plugins/core/README.md#config_output"><code>config_output</code></a> set to either <code>png</code>, <code>jpeg</code> or <code>markdown-pdf</code></p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> commit

<b>allowed values:</b><ul><li>none</li><li>commit</li><li>pull-request</li><li>pull-request-merge</li><li>pull-request-squash</li><li>pull-request-rebase</li><li>gist</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>output_condition</code></h4></td> <td rowspan="2"><p>Output condition</p> <ul> <li><code>always</code>: always try to push changes</li> <li><code>data-changed</code>: skip changes if no data changed (e.g. like when only metadata changed)</li> </ul> <blockquote> <p>ℹī¸ This option is only revelant when <a href="/source/plugins/core/README.md#config_output"><code>config_output: svg</code></a> is set</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> always

<b>allowed values:</b><ul><li>always</li><li>data-changed</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>optimize</code></h4></td> <td rowspan="2"><p>Optimization features</p> <ul> <li><code>css</code>: purge and minify CSS styles</li> <li><code>xml</code>: pretty-print XML (useful to reduce diff)</li> <li><code>svg</code>: optimization with SVGO (experimental, requires <a href="/source/plugins/core/README.md#experimental_features"><code>experimental_features: --optimize-svg</code></a>)</li> </ul> <p>Templates may not always honour all provided options</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>array</code> <i>(comma-separated)</i>

<b>default:</b> css, xml

<b>allowed values:</b><ul><li>css</li><li>xml</li><li>svg</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>setup_community_templates</code></h4></td> <td rowspan="2"><p>Community templates to setup</p> <p>See <a href="https://github.com/lowlighter/metrics/blob/master/source/templates/community/README.md">community templates guide</a> for more informations</p> </td> </tr> <tr> <td nowrap="nowrap">🌐 Web instances must configure <code>settings.json</code>: <ul> <li><i>metrics.setup.community.templates</i></li> </ul> <b>type:</b> <code>array</code> <i>(comma-separated)</i> </td> </tr> <tr> <td nowrap="nowrap"><h4><code>template</code></h4></td> <td rowspan="2"><p>Template</p> <p>Community templates must be prefixed by at sign (<code>@</code>) See <a href="https://github.com/lowlighter/metrics/blob/master/README.md#%EF%B8%8F-templates">list of supported templates</a></p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> classic

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>query</code></h4></td> <td rowspan="2"><p>Query parameters</p> <p>Pass additional parameters to templates. This is mostly useful for custom templates.</p> <blockquote> <p>⚠ī¸ <strong>Do not</strong> use this option to pass other existing parameters, they will be overwritten</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>json</code>

<b>default:</b> <details><summary>→ Click to expand</summary><pre language="json"><code>{}</code></pre></details>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>extras_css</code></h4></td> <td rowspan="2"><p>Extra CSS</p> <p>Custom CSS that will be injected in used template. Useful to avoid creating a new template just to tweak some styling</p> <blockquote> <p>💡 <em>metrics</em> tends to avoid using <code>!important</code> rules, which means that most styling can be overridden by this option when using <code>!important</code></p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">🌐 Web instances must configure <code>settings.json</code>: <ul> <li><i>metrics.run.puppeteer.user.css</i></li> </ul> <b>type:</b> <code>string</code> </td> </tr> <tr> <td nowrap="nowrap"><h4><code>extras_js</code></h4></td> <td rowspan="2"><p>Extra JavaScript</p> <p>Custom JavaScript that will be executed during puppeteer rendering. Useful to avoid creating a new template just to tweak some content.</p> <blockquote> <p>⚠ī¸ Note that is it executed within puppeteer context and <strong>not</strong> within <em>metrics</em> 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.</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">🌐 Web instances must configure <code>settings.json</code>: <ul> <li><i>metrics.run.puppeteer.user.js</i></li> </ul> <b>type:</b> <code>string</code> </td> </tr> <tr> <td nowrap="nowrap"><h4><code>github_api_rest</code></h4></td> <td rowspan="2"><p>GitHub REST API endpoint</p> <p>Can be used to support <a href="https://github.com/enterprise">GitHub enterprises server</a>. Leave empty to use default endpoint.</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>string</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>github_api_graphql</code></h4></td> <td rowspan="2"><p>GitHub GraphQL API endpoint</p> <p>Can be used to support <a href="https://github.com/enterprise">GitHub enterprises server</a>. Leave empty to use default endpoint.</p> <blockquote> <p>ℹī¸ GraphQL octokit will automatically append <code>/graphql</code> to provided endpoint</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>string</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_timezone</code></h4></td> <td rowspan="2"><p>Timezone for dates</p> <p>See <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">list of supported timezone</a></p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>string</code>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_order</code></h4></td> <td rowspan="2"><p>Plugin order</p> <p>By default, templates use <code>partials/_.json</code> ordering. You can override the content order by using this setting.</p> <p>If some partials are omitted, they will be appended at the end with default ordering</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>array</code> <i>(comma-separated)</i>

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_twemoji</code></h4></td> <td rowspan="2"><p>Use twemojis</p> <p>Replace emojis by <a href="%5Btwemojis%5D(https://github.com/twitter/twemoji)">twemojis</a> to have a consistent render across all platforms May increase filesize.</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_gemoji</code></h4></td> <td rowspan="2"><p>Use GitHub custom emojis</p> <p>GitHub supports additional emojis which are not registered in Unicode standard (:octocat:, :shipit:, :trollface:, ...) See full list at <a href="https://api.github.com/emojis">https://api.github.com/emojis</a>.</p> <p>This option has no effect when [`token: NOT_NEEDED``](/source/plugins/core/README.md#token) is set.</p> <p>May increase filesize</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>boolean</code>

<b>default:</b> yes

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_octicon</code></h4></td> <td rowspan="2"><p>Use GitHub octicons</p> <p>Octicons are open-sourced icons provided by GitHub. See full list at <a href="https://primer.style/octicons">https://primer.style/octicons</a>.</p> <p>To include an octicon, use the following syntax: <code>:octicon-{name}-{size}:</code>. Size must be a supported icon size (12, 16 or 24). 16px octicons can omit size and directly use <code>:octicon-{name}:</code> syntax.</p> <p>May increase filesize</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_display</code></h4></td> <td rowspan="2"><p>Display width (for image output formats)</p> <ul> <li><code>regular</code>: 480px width</li> <li><code>large</code>: 960px width (may not be supported by all templates)</li> <li><code>columns</code>: Full width with auto-sizing (two columns for desktops, and one column for mobile)<ul> <li>known issue: <a href="https://github.com/lowlighter/metrics/issues/374">https://github.com/lowlighter/metrics/issues/374</a></li> </ul> </li> </ul> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>string</code>

<b>default:</b> regular

<b>allowed values:</b><ul><li>regular</li><li>large</li><li>columns</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>config_animations</code></h4></td> <td rowspan="2"><p>Use CSS animations</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>boolean</code>

<b>default:</b> yes

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_base64</code></h4></td> <td rowspan="2"><p>Base64-encoded images</p> <p>Enable this option to make self-contained output (i.e. with no external links)</p> </td> </tr> <tr> <td nowrap="nowrap">⏭ī¸ Global option

<b>type:</b> <code>boolean</code>

<b>default:</b> yes

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_padding</code></h4></td> <td rowspan="2"><p>Output padding</p> <p>Although <em>metrics</em> try to auto-guess resulting height, rendering is still dependent on OS and browser settings. It can result in cropped or oversized outputs.</p> <p>This settings let you manually adjust padding with the following format:</p> <ul> <li>1 value for both width and height</li> <li>2 values for width fist and height second, separated by a comma (<code>,</code>)</li> </ul> <p>Each value need to respect the following format:</p> <ul> <li><code>{number}</code></li> <li><code>{number} + {number}%</code></li> <li><code>{number}%</code></li> </ul> <p>Percentage are relative to computed dimensions</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> 0, 8 + 11%

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>config_output</code></h4></td> <td rowspan="2"><p>Output format</p> <ul> <li><code>auto</code>: Template default (usually <code>svg</code> or <code>markdown</code>)</li> <li><code>svg</code>: SVG image</li> <li><code>png</code>: PNG image (animations not supported)</li> <li><code>jpeg</code>: JPEG image (animations and transparency not supported)</li> <li><code>json</code>: JSON data dump</li> <li><code>markdown</code>: Markdown rendered file</li> <li><code>markdown-pdf</code>: PDF from markdown rendered file</li> <li><code>insights</code>: Metrics Insights self-contained HTML file (not configurable)</li> </ul> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>string</code>

<b>default:</b> auto

<b>allowed values:</b><ul><li>auto</li><li>svg</li><li>png</li><li>jpeg</li><li>json</li><li>markdown</li><li>markdown-pdf</li><li>insights</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>config_presets</code></h4></td> <td rowspan="2"><p>Configuration presets</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🌐 Web instances must configure <code>settings.json</code>:

<ul> <li><i>metrics.setup.community.presets</i></li> </ul> <b>type:</b> <code>array</code> <i>(comma-separated)</i> </td> </tr> <tr> <td nowrap="nowrap"><h4><code>retries</code></h4></td> <td rowspan="2"><p>Retries in case of failures (for rendering)</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(1 ≤ đ‘Ĩ ≤ 10)</i>

<b>default:</b> 3

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>retries_delay</code></h4></td> <td rowspan="2"><p>Delay between each retry (in seconds, for rendering)</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(0 ≤ đ‘Ĩ ≤ 3600)</i>

<b>default:</b> 300

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>retries_output_action</code></h4></td> <td rowspan="2"><p>Retries in case of failures (for output action)</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(1 ≤ đ‘Ĩ ≤ 10)</i>

<b>default:</b> 5

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>retries_delay_output_action</code></h4></td> <td rowspan="2"><p>Delay between each retry (in seconds, for output action)</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(0 ≤ đ‘Ĩ ≤ 3600)</i>

<b>default:</b> 120

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>clean_workflows</code></h4></td> <td rowspan="2"><p>Clean previous workflows jobs</p> <p>This can be used to clean up Action tabs from previous workflows runs.</p> <p>Use <code>all</code> to clean up workflows runs in any state.</p> <blockquote> <p>⚠ī¸ When reporting issues, it is <strong>required</strong> to provide logs so it can be investigated and reproduced. Be sure to disable this option when asking for help or submitting bug reports.</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

<b>type:</b> <code>array</code> <i>(comma-separated)</i>

<b>allowed values:</b><ul><li>cancelled</li><li>failure</li><li>success</li><li>skipped</li><li>startup_failure</li><li>timed_out</li><li>all</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>delay</code></h4></td> <td rowspan="2"><p>Job delay</p> <p>This can be used to avoid triggering GitHub abuse mechanics on large workflows</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(0 ≤ đ‘Ĩ ≤ 3600)</i>

<b>default:</b> 0

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>quota_required_rest</code></h4></td> <td rowspan="2"><p>Minimum GitHub REST API requests quota required to run</p> <p>Action will cancel itself without any errors if requirements are not met</p> <p>This option has no effect when <a href="/source/plugins/core/README.md#token"><code>token: NOT_NEEDED</code></a> is set</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(0 ≤ đ‘Ĩ ≤ 5000)</i>

<b>default:</b> 200

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>quota_required_graphql</code></h4></td> <td rowspan="2"><p>Minimum GitHub GraphQL API requests quota required to run</p> <p>Action will cancel itself without any errors if requirements are not met</p> <p>This option has no effect when <a href="/source/plugins/core/README.md#token"><code>token: NOT_NEEDED</code></a> is set</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(0 ≤ đ‘Ĩ ≤ 5000)</i>

<b>default:</b> 200

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>quota_required_search</code></h4></td> <td rowspan="2"><p>Minimum GitHub Search API requests quota required to run</p> <p>Action will cancel itself without any errors if requirements are not met</p> <p>This option has no effect when <a href="/source/plugins/core/README.md#token"><code>token: NOT_NEEDED</code></a> is set</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>number</code> <i>(0 ≤ đ‘Ĩ ≤ 30)</i>

<b>default:</b> 0

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>notice_releases</code></h4></td> <td rowspan="2"><p>Notice about new releases of metrics</p> </td> </tr> <tr> <td nowrap="nowrap"><b>type:</b> <code>boolean</code>

<b>default:</b> yes

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>use_prebuilt_image</code></h4></td> <td rowspan="2"><p>Use pre-built docker image from <a href="https://github.com/lowlighter/metrics/pkgs/container/metrics">GitHub container registry</a></p> <p>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)</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>boolean</code>

<b>default:</b> yes

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>plugins_errors_fatal</code></h4></td> <td rowspan="2"><p>Fatal plugin errors</p> <p>When enabled, the job will fail in case of plugin errors, else it will be handled gracefully in output with an error message</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>debug</code></h4></td> <td rowspan="2"><p>Debug mode</p> <p>This setting is automatically enable if a job fail (useful with <a href="/source/plugins/core/README.md#plugins_errors_fatal"><code>plugins_errors_fatal: yes</code></a>)</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>verify</code></h4></td> <td rowspan="2"><p>SVG validity check</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

🌐 Web instances must configure <code>settings.json</code>:

<ul> <li><i>metrics.npm.optional.libxml2</i></li> </ul> <b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>debug_flags</code></h4></td> <td rowspan="2"><p>Debug flags</p> <ul> <li><code>--cakeday</code>: simulate registration anniversary</li> <li><code>--halloween</code>: enable halloween colors <em>(only first color scheme will be applied if multiple are specified)</em></li> <li><code>--winter</code>: enable winter colors <em>(only first color scheme will be applied if multiple are specified)</em></li> <li><code>--error</code>: force render error</li> <li><code>--puppeteer-debug</code>: enable puppeteer debug mode*</li> <li><code>--puppeteer-disable-headless</code>: disable puppeteer headless mode <em>(requires a graphical environment)</em>*</li> <li><code>--puppeteer-wait-load</code>: override puppeteer wait events*</li> <li><code>--puppeteer-wait-domcontentloaded</code>: override puppeteer wait events*</li> <li><code>--puppeteer-wait-networkidle0</code>: override puppeteer wait events*</li> <li><code>--puppeteer-wait-networkidle2</code>: override puppeteer wait events*</li> </ul> <blockquote> <p><em>* 🌐 Web instances needs to have <a href="/source/plugins/core/README.md#debug"><code>debug</code></a> set in <code>settings.json</code> for these flags to be supported.</em></p> </blockquote> <blockquote> <p>⚠ī¸ No backward compatibility is guaranteed for these features, they are only meant for debugging purposes.</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>array</code> <i>(space-separated)</i>

<b>allowed values:</b><ul><li>--cakeday</li><li>--halloween</li><li>--winter</li><li>--error</li><li>--puppeteer-debug</li><li>--puppeteer-disable-headless</li><li>--puppeteer-wait-load</li><li>--puppeteer-wait-domcontentloaded</li><li>--puppeteer-wait-networkidle0</li><li>--puppeteer-wait-networkidle2</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>debug_print</code></h4></td> <td rowspan="2"><p>Print output in console</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>dryrun</code></h4></td> <td rowspan="2"><p>Dry-run</p> <blockquote> <p>⚠ī¸ Unlike <a href="/source/plugins/core/README.md#output_action"><code>output_action: none</code></a>, output file won&#39;t be available in <code>/metrics_renders</code> directory</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> <tr> <td nowrap="nowrap"><h4><code>experimental_features</code></h4></td> <td rowspan="2"><p>Experimental features</p> <blockquote> <p>⚠ī¸ No backward compatibility is guaranteed for these features</p> </blockquote> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>array</code> <i>(space-separated)</i>

<b>allowed values:</b><ul><li>--optimize-svg</li></ul></td>

</tr> <tr> <td nowrap="nowrap"><h4><code>use_mocked_data</code></h4></td> <td rowspan="2"><p>Use mocked data instead of live APIs</p> </td> </tr> <tr> <td nowrap="nowrap">⏯ī¸ Cannot be preset

🔧 For development

<b>type:</b> <code>boolean</code>

<b>default:</b> no

</td> </tr> </table> <!--/options-->