Want to learn how to build your own GitHub Actions? Click here

YAMLer Action

30 Apr 2021 in Action Spotlight

Process a YAML document and make all the elements available as GitHub Workflow output variables

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.

Fact Sheet

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 description
name: Michael
handle: mheap
- actions-book
- github-default-branch

These variables would be available as follows:

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 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_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.

Whilst processing keys, the action applies the following rules:

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.