Skip to content

Templates

Jump to bottom
John Brunton edited this page Jan 30, 2021 · 14 revisions

GFlows supports Jsonnet and ytt (Yaml Templating Tool). In both cases it uses them in slightly specific ways in order to generate distinct workflows.

Jsonnet

When using Jsonnet, GFlows will treat any file matching the following glob as a workflow template:

.gflows/workflows/**/*.jsonnet

The workflow name will be derived from the jsonnet file name. For example, a template my-workflow.libsonnet will be used to generate a workflow my-workflow.yml.

As with Jsonnet, library (.libsonnet) files can be added anywhere to the file system and referenced with relative paths.

Serialization

By default Jsonnet outputs JSON, but it includes the std.manifestYamlDoc library function to output YAML. To generate a workflow, you need to use this to generate the output:

local workflow = {
  jobs: [
    // ...
  ]
};

std.manifestYamlDoc(workflow)

Jsonnet library files

To add library files or directories to the JPATH, add a templates.libs field to .gflows/config.yml:

templates:
  defaults:
    libs:
    - path/to/my/lib

This is equivalent to jsonnet -J path/to/my/lib.

Note: the local libs directory will be automatically added to the library search path.

You can also add specific libs to specific workflows. See the Configuration docs for more options.

Remote libraries

With GFLows Packages

The easiest way of adding remote libraries is to use the GFlows Packages format.

Jsonnet Bundler

Another option is to use jsonnet-bundler. This is the native Jsonnet approach and it has some advantages (such as versioning), but it may be heavyweight compared to GFlows Libraries.

Any additional library paths should be added to the templates.libs list in the config file. These paths may be relative, so, for example, if you install dependencies into .jflows/vendor, then your config may look like this:

templates:
  defaults:
    libs:
    - vendor

Ytt

When using Ytt, GFlows will treat any directory in .gflows/workflows which itself contains yaml files as a workflow template, named after the directory. For example, given these files:

.gflows/workflows/my-workflow/config.yml
.gflows/workglows/my-worfklow/workflow.yml

GFlows will treat .gflows/workflows/my-workflow as the template for a workflow my-workflow.yml. The file generated will be equivalent to running ytt manually like this:

ytt -f .gflows/workflows/my-workflow

Ytt library files

If you want to add library files (i.e. files which are are used by multiple workflows but which shouldn't be treated as workflow templates themselves), you can do that with the templates.libs property in .gflows/config.yml:

templates:
  defaults:
    libs:
    - my-lib

For example, given these files and the above config:

.gflows/workflows/my-lib/common.yml
.gflows/workflows/my-workflow/config.yml
.gflows/workglows/my-worfklow/workflow.yml

GFlows will treat .gflows/workflows/my-workflow as the template for a workflow my-workflow.yml, and the file generated will be equivalent to running ytt manually like this:

ytt -f .gflows/workflows/my-workflow -f .gflows/workflows/my-lib

Note that the local libs directory will also be automatically added to the library search path.

You can also add remote files:

templates:
  defaults:
    libs:
    - https://raw.githubusercontent.com/jbrunton/my-workflows/develop/common.yml

If you wish to add remote libraries that span multiple files, or to share workflows (not just library files), you may wish to consider using GFlows Packages.

You can also add specific libs to specific workflows. See the Configuration docs for more options.

Development Tips

  • You can get Jsonnet syntax highlighting and autocomplete in VS Code from the Jsonnet Language Support extension.
  • You can get workflow schema validation directly in VS Code if you add the YAML Language Support extension and add the below to your settings.json:
    "yaml.schemas": {
        "https://json.schemastore.org/github-workflow": ["/.github/workflows/*.yml"]
    }

Examples

  • You can find examples of the workflows generated by the init command in the .gflows/examples directory:
  • This PR from another project I was working on shows how I was able to break up two very awkward workflow files into multiple smaller Jsonnet files (and also reduce the loc). It was a large refactor, but was pretty quick and easy given the fast feedback using gflows watch.
Clone this wiki locally