- Parses string, booleans, numbers and arrays to correct JS types
- Supports default values if no input was provided
- Throws errors if input is set to required and is missing
- Uses local environment variables and
.env
files during development - Specify a custom function for advanced parsing
- Supports array of inputs
- Supports Typescript
- Supports parsing multiple inputs
Install github-action-input-parser via npm:
npm install github-action-input-parser
Import github-action-input-parser
and use it like this:
Javascript:
const parser = require('github-action-input-parser');
JS Modules/Typescript:
import * as parser from 'github-action-input-parser';
Let's say you have the following workflow file (see below on how to specify inputs during development):
uses: username/action
with:
names: |
Maximilian
Richard
Pass an options object to the getInput
function to specify an array of String
type:
const value = parser.getInput({
input: 'names',
type: <const>[String],
});
// [ 'Maximilian', 'Richard' ]
github-action-input-parser will parse the names
input and return an array.
See below for all options or checkout a few more examples.
You can pass the following object to getInput
to tell github-action-input-parser what to parse:
const options = {
input: 'names',
type: <const>[String],
default: <const>['maximilian'],
};
parser.getInput(options);
Here are all the options you can use and there default values:
Name | Description | Required | Default | See more |
---|---|---|---|---|
input |
The input name (can also be an array of inputs) | Yes | N/A | Input |
type |
The type of the input value | No | String |
Types |
required |
Specify if the input is required | No | false | Required Inputs |
default |
Specify a default value for the input | No | undefined | Default Values |
You can either specify a single input as a string, or multiple inputs as an array of strings. This options declares which input(s) should be parsed. When using an array of inputs the first input defined will be picked for parsing.
Note: Even when the chosen input can not be parsed for the given type, github-action-input-parser will not try another input and instead throw an error
You can specify one of the following basic types (BaseTypes) which will determine how the input is parsed:
String
- Default type, the input value will only be trimmedBoolean
- Will parse a boolean based on the yaml 1.2 specificationNumber
- Will convert the input to a number(value: string) => any
/Function
- Will call the function specified to parse an input. Use this for custom types
Note:
String
,Boolean
andNumber
are literals of typeStringConstructor
,BooleanConstructor
andNumberConstructor
respectively
Note: if the input can not be converted to the specifed type, an error is thrown
Additionally you can specifiy an array with the 4 BaseTypes as elements. When using typescript it is recommended to prefix the array with <const>
or suffix it with as const
for optimal type-hinting. The meaning of the array type depends on the amount of its elements:
- 0 elements - not allowed, github-action-input-parser will throw an error
- 1 element - github-action-input-parser will treat this type as an Array Type and tries parsing the input for any number of elements separated by a comma or a newline using the parser specified by the BaseType inside the type array
- 2+ elements - github-action-input-parser will treat this type as a Tuple Type and tries parsing the input for as many elements separated by a comma or a newline as the number of elements in the type array. The parser used depends on the type at the equivalent index in the type array
When you set required to true and the input(s) are not set or could not be parsed, github-action-input-parser will throw an error. When using an array type github-action-input-parser will check each element of the resulting array and if any of them could not be parsed github-action-input-parser will throw an error.
You can specify a default value for the input which will be used when the input is not set. How this default value will be used depends on its type and the type of the parsed content:
type option |
default value type | behavior |
---|---|---|
BaseTypes | any | The default value replaces the parsed value if the parsed value is undefined |
ArrayType or TupleType | any non-array | The default value replaces any undefined elements of the parsed array. However the default value will not replace the parsed value itself if it ends up being undefined (e.g. when the input is not set) |
ArrayType or TupleType | any array | The elements of the default value replace any undefined element at the same index in the parsed array. If the parsed array is longer than the default value array this can result in undefined elements beyond the length of the default value array. The default value array will replace the parsed array if it is undefined |
If you run your Action locally during development, you can set the inputs as environment variables or specify them in a .env
file. github-action-input-parser will use them as the inputs automatically.
This library has Typescript support but to get the most out of it you have to prefix any array passed to the configuration options type and default with <const>
or suffix them with as const
.
To parse multiple inputs with different configurations into one options you can use the getInputs()
function. It takes an object where each element is either an argument for getInput()
(string | string[] | Options
) or undefined
. When an element is undefined
the key will be used as the input name.
Here are some examples on how to use github-action-input-parser:
See README.test.ts
Action Workflow:
uses: username/action
with:
name: Maximilian
Action code:
const value = parser.getInput('name');
// value -> Maximilian
or
const value = parser.getInput({
input: 'name',
});
// value -> Maximilian
Action Workflow:
uses: username/action
with:
dry_run: true
Action code:
const value = parser.getInput({
input: 'dry_run',
type: Boolean,
});
// Without setting the type to boolean, the value would have been 'true'
Action Workflow:
uses: username/action
with:
stages: |
'dev'
'prod'
Action code:
const value = parser.getInput({
input: 'stages',
type: <const>[String],
});
// ['dev', 'prod']
Action Workflow:
uses: username/action
with:
fruits: |
10
apples
Action code:
const value = parser.getInput({
input: 'fruits',
type: <const>[Number, String],
});
// [10, 'apples']
Action Workflow:
uses: username/action
with:
Action code:
const value = parser.getInput({
input: 'name',
default: 'Maximilian',
});
// As name is not set, Maximilian will be returned as the name
Action Workflow:
uses: username/action
with:
command: |
bring me
apples
Action code:
const value = parser.getInput({
input: 'command',
type: <const>[String, Number, String],
default: <const>[undefined, 10],
});
// ['bring me', 10, 'apples']
Action Workflow:
uses: username/action
with:
Action code:
const value = parser.getInput({
input: 'name',
required: true,
});
// Will throw an error if name is not set
Action Workflow:
uses: username/action
with:
GH_PAT: 'abcdefghijklmnopqrstuvwxyz';
Action code:
const value = parser.getInput({
input: [ 'GITHUB_TOKEN', 'GH_PAT' ]
});
// The first input available takes precedence -> GH_PATs value will be parsed
Action code:
Javascript:
uses: username/action
with:
greeting: 'Hello world!'
GH_PAT: 'abcdefghijklmnopqrstuvwxyz'
const {value1, value2, value3} = parser.getInputs({
value1: 'greeting',
value2: {
input: [ 'GITHUB_TOKEN', 'GH_PAT' ],
required: true,
},
value3: {
input: 'max retires',
type: Number,
default: 3,
},
});
// value1 = 'Hello world!', value2 = 'abcdefghijklmnopqrstuvwxyz', value3 = 3
Action Workflow:
uses: username/action
with:
github_token: TOKEN
repository: username/reponame
labels: |
merged
ready
Action code:
const config = getInputs({
githubToken: {
input: 'github_token',
required: true,
},
repository: {
input: 'repository',
type: (val) => {
const [user, repo] = val.split('/')
return { user, repo }
},
},
labels: {
input: 'labels',
type: <const>[String],
},
dryRun: {
input: 'dry_run',
type: Boolean,
default: false,
},
});
// parsed config:
{
githubToken: 'TOKEN',
repository: {
name: 'username',
repo: 'reponame'
},
labels: [ 'merged', 'ready' ],
dryRun: false,
}
See index.test.ts
Issues and PRs are very welcome!
The actual source code of this library is in the src
folder.
- run
yarn lint
ornpm run lint
to run eslint. - run
yarn build
ornpm run build
to produce a compiled version in thelib
folder.
This project was originally developed by (@betahuhn) and was heavily modified by (@pdamianik) in their free time. If you want to support @betahuhn:
Copyright 2021 Maximilian Schiller
Copyright 2022 Philip Damianik
This project is licensed under the MIT License - see the LICENSE file for details.