YAMLer Action

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:

yaml
summary: This is a description
contributor:
  name: Michael
  handle: mheap
projects:
  - actions-book
  - github-default-branch

These variables would be available as follows:

yaml
summary: This is a description
contributor__name: Michael
contributor__handle: mheap
contributor__projects__0: actions-book
contributor__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
YAML Resources:
  YAML 1.2 (3rd Edition): http://yaml.org/spec/1.2/spec.html
  YAML 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
yaml_resources__yaml_1_2_3rd_edition: http://yaml.org/spec/1.2/spec.html
yaml_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 traverseArray or traverseObject as required.
  • Calling traverseArray loops over all values in the array and emits a new value if we detect a scalar
  • Calling traverseObject is 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, /, -, . or : with an underscore
• Remove parenthesis (), square brackets [], single quotes and commas
• Replace + with p
• Replace # with s

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 build directory.

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.