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 *(only first color scheme will be applied if multiple are specified)*
      - `--winter`: enable winter colors *(only first color scheme will be applied if multiple are specified)*
      - `--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
      - --winter
      - --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