When running your workflows, sometimes you need to read information from a file in your repository.
YAMLer parses the provided YAML file and makes the values in the file available as output variables.
What does it do?
YAMLer takes each field in the provided YAML document and makes it available as an output variable. Nested resources are nested using a double underscore (
Take the following YAML file as an input:
summary: This is a descriptioncontributor:name: Michaelhandle: mheapprojects:- actions-book- github-default-branch
These variables would be available as follows:
summary: This is a descriptioncontributor__name: Michaelcontributor__handle: mheapcontributor__projects__0: actions-bookcontributor__projects__1: github-default-branch
The action works for deeply nested values and has been tested with scalars (strings, numbers, booleans), objects and arrays.
In addition to making nested properties available, the action also handles special characters.
Using the sample from the YAML.org test file, we can see that periods and parenthesis are replaced:
YAML Resources:YAML 1.2 (3rd Edition): http://yaml.org/spec/1.2/spec.htmlYAML 1.1 (2nd Edition): http://yaml.org/spec/1.1/YAML 1.0 (1st Edition): http://yaml.org/spec/1.0/YAML Issues Page: https://github.com/yaml/yaml/issues
Is made available as:
yaml_resources__yaml_1_2_3rd_edition: http://yaml.org/spec/1.2/spec.htmlyaml_resources__yaml_1_1_2nd_edition: http://yaml.org/spec/1.1/yaml_resources__yaml_1_0_1st_edition: http://yaml.org/spec/1.0/yaml_resources__yaml_issues_page: https://github.com/yaml/yaml/issues
Notice how the periods are replaced with underscores, and the parenthesis are removed? Let’s take a look at the rules for replacement in the source!
How does it work?
The entire action is available in a single file which makes it easy to understand what’s going on.
The entry point reads the file provided in the
yaml-file input and passes it to
traverseObject to start building the output. This method iterates over the keys in the provided YAML file and decides how to process each entry.
- If the value is a scalar (string, number or boolean) we’re at the end of a nested value (the leaf) and it’s time to add an output
- If the value is an object or an array, we keep track of all the keys we saw whilst traversing to this depth and then call either
traverseArrayloops over all values in the array and emits a new value if we detect a scalar
traverseObjectis a recursive call which starts this set of bullet points again with the child value passed in as the argument
Whilst processing keys, the action applies the following rules:
- Replace whitespace,
:with an underscore
- Remove parenthesis
(), square brackets
, single quotes and commas
The last two substitutions seem strange to me, but I guess the author had a use case where it made sense.
As mentioned earlier, the action has a single required input which is the path to the YAML file to read. It runs using the
node12 runtime thanks to a compiled version of the action being available in the
Finally, the action uses semantic versioning. It’s currently at
v0 whilst it’s in beta, and uses the release-github-actions action to automatically build and commit an updated
build/index.js file when a release is created. Then the major and minor tags are updated to point at the new release commit.