metrics/source/plugins/core/metadata.yml

name: "🧱 Core"
cost: N/A
category: core
supports:
  - user
  - organization
  - repository
inputs:

  # User account personal token
  # No additional scopes are needed unless you want to include private repositories metrics
  # Some plugins may also require additional scopes
  # ────────────────────────────────────────────────────────────────
  # If you're only using plugins which don't really require a GitHub token, you may pass "NOT_NEEDED" as value
  token:
    description: GitHub Personal Token
    type: token
    required: true

  # GitHub username
  # Defaults to "token" owner
  user:
    description: GitHub username
    type: string
    default: ""

  # GitHub repository
  # Compute metrics for a repository instead ("user" being the repository owner)
  # Check https://github.com/lowlighter/metrics/blob/master/source/templates/repository/README.md for more informations
  repo:
    description: GitHub repository
    type: string
    default: ""

  # Set to "${{ github.token }}" or "${{ secrets.GITHUB_TOKEN }}"
  # GITHUB_TOKEN is a special auto-generated token restricted to current repository, which is used to push files in it
  committer_token:
    description: GitHub Token used to commit metrics
    type: token
    default: ${{ github.token }}

  # Branch used to commit rendered metrics
  committer_branch:
    description: Branch used to commit rendered metrics
    type: string
    default: "" # Defaults to your repository default branch

  # Commit message
  # Use "${filename}" to display filename
  committer_message:
    description: Commit message
    type: string
    default: Update ${filename} - [Skip GitHub Action]

  # Instead of saving metrics to a repository, it's possible to save them to a gist to avoid "commits pollution"
  # Gist must be created prior and you must pass its identifier in the following option
  # Set "gist" in "output_action" to use this option
  committer_gist:
    description: Gist used to store metrics
    type: string
    default: ""

  # Rendered metrics output path, relative to repository's root
  # When using "*", the correct extension will automatically on "config_output" value
  filename:
    description: Rendered metrics output path
    type: string
    default: github-metrics.*

  # Rendered markdown output path (when using a markdown template)
  # It can be either a local path or a link (e.g. raw.githubusercontent.com)
  markdown:
    description: Rendered markdown output path
    type: string
    default: TEMPLATE.md

  # Rendered markdown file cache (when using a markdown template)
  markdown_cache:
    description: Rendered markdown file cache
    type: string
    default: .cache

  # Output action
  output_action:
    description: Output action
    type: string
    default: commit
    values:
      - none                # Only generate file in "/metrics_renders"
      - commit              # Commit output to "committer_branch"
      - pull-request        # Commit output to a new branch and open a pull request to "committer_branch"
      - pull-request-merge  # Same as "pull-request" and additionaly merge pull request
      - pull-request-squash # Same as "pull-request" and additionaly squash and merge pull request
      - pull-request-rebase # Same as "pull-request" and additionaly rebase and merge pull request
      - gist                # Save output to "committer_gist"

  # Output condition
  output_condition:
    description: Output condition
    type: string
    default: always
    values:
      - always                        # Always push changes
      - skip-if-only-metadata-changed # Skip changes if only metadata contained in footer changed

  # Optimize SVG image to reduce its filesize
  # Some templates may not support this option
  optimize:
    description: SVG optimization
    type: boolean
    default: yes

  # Setup additional templates from remote repositories
  setup_community_templates:
    description: Additional community templates to setup
    type: array
    format:
      - comma-separated
      - /(?<user>[-a-z0-9]+)[/](?<repo>[-a-z0-9]+)@(?<branch>[-a-z0-9]+):(?<template>[-a-z0-9]+)/
    default: ""

  # Template to use
  # To use community template, prefix its name with "@"
  template:
    description: Template to use
    type: string
    default: classic

  # Additional query parameters (JSON string)
  # Some templates may require additional parameters which you can specify here
  # Do not use this option to pass plugins parameters as they'll be overwritten by the other options
  query:
    description: Additional query parameters
    type: json
    default: "{}"

  # Define additional CSS that will be injected in used template
  # Example:
  # config_extras_css꞉ |
  #   h2 {
  #     color: red;
  #   }
  extras_css:
    description: Extra CSS
    type: string
    default: ""

  # Timezone used by metrics
  # See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  config_timezone:
    description: Timezone used
    type: string
    default: ""

  # Specify in which order metrics content will be displayed
  # If you omit some partials, they'll be appended at the end in default order
  # See "partials/_.json" of each template for a list of supported partials
  config_order:
    description: Configure content order
    type: array
    format: comma-separated
    default: ""
    example: base.header, base.repositories

  # Use twemojis instead of emojis
  # May increase filesize but emojis will be rendered the same across all platforms
  config_twemoji:
    description: Use twemojis instead of emojis
    type: boolean
    default: no

  # Render GitHub custom emojis (like ":octocat:", see full list at https://api.github.com/emojis)
  # May increase filesize
  config_gemoji:
    description: Use GitHub custom emojis
    type: boolean
    default: yes

  # Render display width
  config_display:
    description: Render display width
    type: string
    default: regular
    values:
      - regular  # 480px width
      - large    # 960px width (may not be supported by all templates)
      - columns  # Full width with two columns on desktop / One column on mobile

  # Enable SVG CSS animations
  config_animations:
    description: SVG CSS animations
    type: boolean
    default: yes

  # Encode images links into base64 data
  # Advised to be true when generating images and false when generating texts or JSON
  config_base64:
    description: Encode images links into base64 data
    type: boolean
    default: yes

  # Configure padding for output image (percentage value)
  # It can be used to add padding to generated metrics if rendering is cropped or has too much empty space
  # Specify one value (for both width and height) or two values (one for width and one for height)
  config_padding:
    description: Image padding
    type: string
    default: 0, 8 + 11%

  # Metrics output format
  config_output:
    description: Output image format
    type: string
    default: auto
    values:
      - auto           # Defaults to template default
      - svg
      - png            # Does not support animations
      - jpeg           # Does not support animations and transparency
      - json           # Outputs a JSON file instead of an image
      - markdown       # Outputs a Markdown file instead of an image
      - markdown-pdf   # Outputs a Markdown file as PDF instead of an image
      - insights       # Outputs a rendered HTML file of Metrics Insights

  # Number of retries in case rendering fail
  retries:
    description: Number of retries
    type: number
    default: 3
    min: 1
    max: 10

  # Time to wait (in seconds) before each retry
  retries_delay:
    description: Time to wait (in seconds) before each retry
    type: number
    default: 300
    min: 0
    max: 3600

  # ====================================================================================
  # 🚧 Options below are mostly used for testing

  # Throw on plugins errors
  # If disabled, metrics will handle errors gracefully with a message in rendered metrics
  plugins_errors_fatal:
    description: Die on plugins errors
    type: boolean
    default: no

  # Debug mode
  # Note that this will automatically be enabled if job fails
  debug:
    description: Debug logs
    type: boolean
    default: no

  # Ensure SVG can be correctly parsed after generation
  verify:
    description: Verify SVG
    type: boolean
    default: no

  # Debug flags
  debug_flags:
    description: Debug flags
    type: array
    format: space-separated
    default: ""
    values:
      - --cakeday
      - --hireable
      - --halloween
      - --error

  # Dry-run mode (perform generation without output)
  # Unlike "output_action" set to "none", output file won't be available in "/metrics_renders"
  dryrun:
    description: Enable dry-run
    type: boolean
    default: no

  # Experimental features
  experimental_features:
    description: Experimental features
    type: array
    format: space-separated
    default: ""
    values:
      - --optimize

  # Use mocked data to bypass external APIs
  use_mocked_data:
    description: Use mocked data instead of live APIs
    type: boolean
    default: no

  # Use a pre-built image from GitHub registry when using unreleased versions of "lowlighter/metrics"
  # This option has no effect on forks (images will always be rebuilt from Dockerfile)
  # See https://github.com/users/lowlighter/packages/container/package/metrics for more information
  use_prebuilt_image:
    description: Use pre-built image from GitHub registry
    type: boolean
    default: yes

  # Time to wait (in seconds) at the end of job
  # Use this to avoid triggering abuse mechanics on large workflows
  delay:
    description: Use this to avoid triggering abuse mechanics on large workflows
    type: number
    default: 0
    min: 0
    max: 3600