605 lines
17 KiB
YAML
605 lines
17 KiB
YAML
name: 🧱 Core
|
||
category: core
|
||
description: Global configuration and options
|
||
supports:
|
||
- user
|
||
- organization
|
||
- repository
|
||
scopes: []
|
||
inputs:
|
||
|
||
token:
|
||
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 `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.
|
||
type: token
|
||
required: true
|
||
|
||
user:
|
||
description: |
|
||
GitHub username
|
||
|
||
Defaults to [`token`](/source/plugins/core/README.md#token) owner username.
|
||
type: string
|
||
default: ""
|
||
preset: no
|
||
|
||
repo:
|
||
description: |
|
||
GitHub repository
|
||
|
||
This option is only revelant for repositories templates
|
||
type: string
|
||
default: ""
|
||
preset: no
|
||
|
||
committer_token:
|
||
description: |
|
||
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`](/source/plugins/core/README.md#output_action), it will use [`token`](/source/plugins/core/README.md#token) instead, since gists are outside of scope
|
||
type: token
|
||
default: ${{ github.token }}
|
||
|
||
committer_branch:
|
||
description: |
|
||
Target branch
|
||
|
||
Defaults to current repository default branch
|
||
type: string
|
||
default: ""
|
||
|
||
committer_message:
|
||
description: |
|
||
Commit message
|
||
|
||
Use `${filename}` to display filename
|
||
type: string
|
||
default: Update ${filename} - [Skip GitHub Action]
|
||
|
||
committer_gist:
|
||
description: |
|
||
Gist id
|
||
|
||
Specify an existing gist id (can be retrieved from its URL) when using [`output_action: gist`](/source/plugins/core/README.md#output_action).
|
||
type: string
|
||
default: ""
|
||
preset: no
|
||
|
||
filename:
|
||
description: |
|
||
Output path
|
||
|
||
When using an asterisk (`*`), correct extension will automatically be applied according to [`config_output`](/source/plugins/core/README.md#config_output) value
|
||
type: string
|
||
default: github-metrics.*
|
||
|
||
markdown:
|
||
description: |
|
||
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:
|
||
description: |
|
||
Markdown file cache
|
||
type: string
|
||
default: .cache
|
||
|
||
output_action:
|
||
description: |
|
||
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`](/source/plugins/core/README.md#config_output) set to either `png`, `jpeg` or `markdown-pdf`
|
||
type: string
|
||
default: commit
|
||
values:
|
||
- none
|
||
- commit
|
||
- pull-request
|
||
- pull-request-merge
|
||
- pull-request-squash
|
||
- pull-request-rebase
|
||
- gist
|
||
|
||
output_condition:
|
||
description: |
|
||
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`](/source/plugins/core/README.md#config_output) is set
|
||
type: string
|
||
default: always
|
||
values:
|
||
- always
|
||
- data-changed
|
||
|
||
optimize:
|
||
description: |
|
||
Optimization features
|
||
- `css`: purge and minify CSS styles
|
||
- `xml`: pretty-print XML (useful to reduce diff)
|
||
- `svg`: optimization with SVGO (experimental, requires [`experimental_features: --optimize-svg`](/source/plugins/core/README.md#experimental_features))
|
||
|
||
Templates may not always honour all provided options
|
||
type: array
|
||
default: css, xml
|
||
format: comma-separated
|
||
values:
|
||
- css
|
||
- xml
|
||
- svg
|
||
|
||
setup_community_templates:
|
||
description: |
|
||
Community templates to setup
|
||
|
||
See [community templates guide](https://github.com/lowlighter/metrics/blob/master/source/templates/community/README.md) for more informations
|
||
type: array
|
||
format: comma-separated
|
||
default: ""
|
||
extras:
|
||
- metrics.setup.community.templates
|
||
|
||
template:
|
||
description: |
|
||
Template
|
||
|
||
Community templates must be prefixed by at sign (`@`)
|
||
See [list of supported templates](https://github.com/lowlighter/metrics/blob/master/README.md#%EF%B8%8F-templates)
|
||
type: string
|
||
default: classic
|
||
|
||
query:
|
||
description: |
|
||
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: "{}"
|
||
|
||
extras_css:
|
||
description: |
|
||
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`
|
||
type: string
|
||
default: ""
|
||
extras:
|
||
- metrics.run.puppeteer.user.css
|
||
|
||
extras_js:
|
||
description: |
|
||
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.
|
||
type: string
|
||
default: ""
|
||
extras:
|
||
- metrics.run.puppeteer.user.js
|
||
|
||
github_api_rest:
|
||
description: |
|
||
GitHub REST API endpoint
|
||
|
||
Can be used to support [GitHub enterprises server](https://github.com/enterprise).
|
||
Leave empty to use default endpoint.
|
||
type: string
|
||
default: ""
|
||
example: https://api.github.com
|
||
global: yes
|
||
|
||
github_api_graphql:
|
||
description: |
|
||
GitHub GraphQL API endpoint
|
||
|
||
Can be used to support [GitHub enterprises server](https://github.com/enterprise).
|
||
Leave empty to use default endpoint.
|
||
|
||
> ℹ️ GraphQL octokit will automatically append `/graphql` to provided endpoint
|
||
type: string
|
||
default: ""
|
||
example: https://api.github.com
|
||
global: yes
|
||
|
||
config_timezone:
|
||
description: |
|
||
Timezone for dates
|
||
|
||
See [list of supported timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
|
||
type: string
|
||
default: ""
|
||
global: yes
|
||
|
||
config_order:
|
||
description: |
|
||
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
|
||
type: array
|
||
format: comma-separated
|
||
default: ""
|
||
example: base.header, base.repositories
|
||
global: yes
|
||
|
||
config_twemoji:
|
||
description: |
|
||
Use twemojis
|
||
|
||
Replace emojis by [twemojis]([twemojis](https://github.com/twitter/twemoji)) to have a consistent render across all platforms
|
||
May increase filesize.
|
||
type: boolean
|
||
default: no
|
||
global: yes
|
||
|
||
config_gemoji:
|
||
description: |
|
||
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
|
||
type: boolean
|
||
default: yes
|
||
global: yes
|
||
|
||
config_octicon:
|
||
description: |
|
||
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
|
||
type: boolean
|
||
default: no
|
||
global: yes
|
||
|
||
config_display:
|
||
description: |
|
||
Display width (for image output formats)
|
||
|
||
- `regular`: 480px width
|
||
- `large`: 960px width (may not be supported by all templates)
|
||
- `columns`: Full width with auto-sizing (two columns for desktops, and one column for mobile)
|
||
- known issue: https://github.com/lowlighter/metrics/issues/374
|
||
type: string
|
||
default: regular
|
||
values:
|
||
- regular
|
||
- large
|
||
- columns
|
||
global: yes
|
||
|
||
config_animations:
|
||
description: |
|
||
Use CSS animations
|
||
type: boolean
|
||
default: yes
|
||
global: yes
|
||
|
||
config_base64:
|
||
description: |
|
||
Base64-encoded images
|
||
|
||
Enable this option to make self-contained output (i.e. with no external links)
|
||
type: boolean
|
||
default: yes
|
||
global: yes
|
||
|
||
config_padding:
|
||
description: |
|
||
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:
|
||
description: |
|
||
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
|
||
values:
|
||
- auto
|
||
- svg
|
||
- png
|
||
- jpeg
|
||
- json
|
||
- markdown
|
||
- markdown-pdf
|
||
- insights
|
||
|
||
config_presets:
|
||
description: |
|
||
Configuration presets
|
||
type: array
|
||
format: comma-separated
|
||
default: ""
|
||
preset: no
|
||
example: "@lunar-red"
|
||
extras:
|
||
- metrics.setup.community.presets
|
||
|
||
retries:
|
||
description: |
|
||
Retries in case of failures (for rendering)
|
||
type: number
|
||
default: 3
|
||
min: 1
|
||
max: 10
|
||
|
||
retries_delay:
|
||
description: |
|
||
Delay between each retry (in seconds, for rendering)
|
||
type: number
|
||
default: 300
|
||
min: 0
|
||
max: 3600
|
||
|
||
retries_output_action:
|
||
description: |
|
||
Retries in case of failures (for output action)
|
||
type: number
|
||
default: 5
|
||
min: 1
|
||
max: 10
|
||
|
||
retries_delay_output_action:
|
||
description: |
|
||
Delay between each retry (in seconds, for output action)
|
||
type: number
|
||
default: 120
|
||
min: 0
|
||
max: 3600
|
||
|
||
clean_workflows:
|
||
description: |
|
||
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.
|
||
type: array
|
||
format: comma-separated
|
||
default: ""
|
||
preset: no
|
||
example: ""
|
||
values:
|
||
- cancelled
|
||
- failure
|
||
- success
|
||
- skipped
|
||
- startup_failure
|
||
- timed_out
|
||
- all
|
||
|
||
delay:
|
||
description: |
|
||
Job delay
|
||
|
||
This can be used to avoid triggering GitHub abuse mechanics on large workflows
|
||
type: number
|
||
default: 0
|
||
min: 0
|
||
max: 3600
|
||
|
||
quota_required_rest:
|
||
description: |
|
||
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`](/source/plugins/core/README.md#token) is set
|
||
type: number
|
||
default: 200
|
||
min: 0
|
||
max: 5000
|
||
|
||
quota_required_graphql:
|
||
description: |
|
||
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`](/source/plugins/core/README.md#token) is set
|
||
type: number
|
||
default: 200
|
||
min: 0
|
||
max: 5000
|
||
|
||
quota_required_search:
|
||
description: |
|
||
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`](/source/plugins/core/README.md#token) is set
|
||
type: number
|
||
default: 0
|
||
min: 0
|
||
max: 30
|
||
|
||
notice_releases:
|
||
description: |
|
||
Notice about new releases of metrics
|
||
type: boolean
|
||
default: yes
|
||
|
||
# ====================================================================================
|
||
# 🚧 Options below are mostly used for testing
|
||
|
||
use_prebuilt_image:
|
||
description: |
|
||
Use pre-built docker image from [GitHub container registry](https://github.com/lowlighter/metrics/pkgs/container/metrics)
|
||
|
||
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)
|
||
type: boolean
|
||
default: yes
|
||
testing: yes
|
||
preset: no
|
||
|
||
plugins_errors_fatal:
|
||
description: |
|
||
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
|
||
type: boolean
|
||
default: no
|
||
testing: yes
|
||
preset: no
|
||
|
||
debug:
|
||
description: |
|
||
Debug mode
|
||
|
||
This setting is automatically enable if a job fail (useful with [`plugins_errors_fatal: yes`](/source/plugins/core/README.md#plugins_errors_fatal))
|
||
type: boolean
|
||
default: no
|
||
testing: yes
|
||
preset: no
|
||
|
||
verify:
|
||
description: |
|
||
SVG validity check
|
||
type: boolean
|
||
default: no
|
||
testing: yes
|
||
preset: no
|
||
extras:
|
||
- metrics.npm.optional.libxml2
|
||
|
||
debug_flags:
|
||
description: |
|
||
Debug flags
|
||
- `--cakeday`: simulate registration anniversary
|
||
- `--halloween`: enable halloween colors
|
||
- `--error`: force render error
|
||
- `--puppeteer-debug`: enable puppeteer debug mode\*
|
||
- `--puppeteer-disable-headless`: disable puppeteer headless mode *(requires a graphical environment)*\*
|
||
- `--puppeteer-wait-load`: override puppeteer wait events\*
|
||
- `--puppeteer-wait-domcontentloaded`: override puppeteer wait events\*
|
||
- `--puppeteer-wait-networkidle0`: override puppeteer wait events\*
|
||
- `--puppeteer-wait-networkidle2`: override puppeteer wait events\*
|
||
|
||
> *\* 🌐 Web instances needs to have [`debug`](/source/plugins/core/README.md#debug) set in `settings.json` for these flags to be supported.*
|
||
|
||
> ⚠️ No backward compatibility is guaranteed for these features, they are only meant for debugging purposes.
|
||
type: array
|
||
format: space-separated
|
||
default: ""
|
||
values:
|
||
- --cakeday
|
||
- --halloween
|
||
- --error
|
||
- --puppeteer-debug
|
||
- --puppeteer-disable-headless
|
||
- --puppeteer-wait-load
|
||
- --puppeteer-wait-domcontentloaded
|
||
- --puppeteer-wait-networkidle0
|
||
- --puppeteer-wait-networkidle2
|
||
testing: yes
|
||
preset: no
|
||
|
||
debug_print:
|
||
description: |
|
||
Print output in console
|
||
type: boolean
|
||
default: no
|
||
testing: yes
|
||
preset: no
|
||
|
||
dryrun:
|
||
description: |
|
||
Dry-run
|
||
|
||
> ⚠️ Unlike [`output_action: none`](/source/plugins/core/README.md#output_action), output file won't be available in `/metrics_renders` directory
|
||
type: boolean
|
||
default: no
|
||
testing: yes
|
||
preset: no
|
||
|
||
experimental_features:
|
||
description: |
|
||
Experimental features
|
||
|
||
> ⚠️ No backward compatibility is guaranteed for these features
|
||
type: array
|
||
format: space-separated
|
||
default: ""
|
||
values:
|
||
- --optimize-svg
|
||
testing: yes
|
||
preset: no
|
||
|
||
use_mocked_data:
|
||
description: |
|
||
Use mocked data instead of live APIs
|
||
type: boolean
|
||
default: no
|
||
testing: yes
|
||
preset: no
|