README.md

GitHub Badge action

This module generates a SVG badge using GitHub Actions inputs and outputs. The badge is generated using the NPM package gradient-badge and echoed as a GitHub Action output, and saved into a file if a path is given. This is the core of the GitHub Action Badge action.

Install

With npm:

npm install github-badge-action

With yarn:

yarn add github-badge-action

Usage

const { createBadgeFromInputs } = require('github-badge-action');
createBadgeFromInputs();

Inputs

Inputs are read from action's inputs using core.input, fixed and passed directly to gradient-badge.

Change input names

The input names are taken from createBadgeFromInputs's inputMap argument, which has this deafults:

const defaultInputMap = {
  label: 'label',
  labelColor: 'label-color',
  status: 'status',
  gradient: 'color',
  style: 'style',
  icon: 'icon',
  iconWidth: 'icon-width',
  scale: 'scale',
  path: 'path',
};

You can import it and modify just some of the options names:

const {
  createBadgeFromInputs,
  defaultInputMap
} = require('github-badge-action');

createBadgeFromInputs({
  inputMap: {
    ...defaultInputMap,
    gradient: 'gradient',
  },
});

Change input fixes

Once the inputs are read, some fixes are applied. The default ones are:

const defaultInputFixes = {
  // Ensure string
  status: (status) => `${status}`,

  // Ensure null if empty
  icon: (icon) => icon?.length ? icon : null,

  // Color gradient as Array
  gradient: (gradient) => gradient
      .split(',')
      // Clean spaces
      .map((color) => color.trim(' ')),
};

You can also change the fixes applied to the inputs, or add more using inputFixes option:

const {
  createBadgeFromInputs,
  defaultInputFixes
} = require('github-badge-action');

createBadgeFromInputs({
  inputFixes: {
    ...defaultInputFixes,
    // Color gradient as Array, split with a pipe '|' instead of a comma ','
    gradient: ({ gradient }) => gradient
        .split('|')
        // Clean spaces
        .map((color) => color.trim(' ')),
  },
});

Available options

label

Required The left label of the badge, usually static.

label-color

Required Hex or named color for the label. Default: 555

status

Required The right status as the badge, usually based on results.

color

Required An array (comma separated) with hex or named colors of the badge value background. More than one creates gradient background. Default: blue.

style

Required Badge style: flat or classic. Default: classic

icon

Use icon.

icon-width

Set this if icon is not square. Default: 13

scale

Set badge scale. Default: 1

path

The file path to store the badge image file. Only output to badge action output if not defined.

Outputs

badge

Once the badge is generated, the SVG contents are written to an action output (by default). The name of the output can be modified using outputName option:

createBadgeFromInputs({
  outputName: 'badge-svg-custom'
});

If the option is null or empty, output will not be written. The default option name is badge.