@allejo/gha-workflows

GitHub Actions does not support YAML anchors and it is incredibly annoying when it comes to reusing anything within those YAML files. So this is a stupid simple script that will expand YAML references and allow you to, sigh, compile your workflows.

This project was inspired by mithro's actions-includes project but it doesn't introduce any custom syntax. I also needed this in my JavaScript project pipelines and I did not want to setup Python just for that script.

At its core, this project is powered by js-yaml.

Example

Source YAML

name: Deployment

on:
  push:
    branches:
      - master
      - develop

jobs:
  production:
    name: Production Deployment
    runs-on: ubuntu-latest
    if: ${{ github.ref == 'refs/heads/master' }}
    environment:
      name: Production
      url: https://example.com/product
    steps: &production_steps
      - uses: actions/checkout@v2

  staging:
    name: Staging Deployment
    runs-on: ubuntu-latest
    if: ${{ github.ref == 'refs/heads/develop' }}
    environment:
        name: Staging
        url: https://staging.example.com/product

    # Handled via the `gha-workflows` CLI since GHA doesn't support YAML anchors
    #   see https://github.community/t/support-for-yaml-anchors/16128
    steps: *production_steps

Output YAML

name: Deployment
'on':
  push:
    branches:
      - master
      - develop
jobs:
  production:
    name: Production Deployment
    runs-on: ubuntu-latest
    if: ${{ github.ref == 'refs/heads/master' }}
    environment:
      name: Production
      url: https://example.com/product
    steps:
      - uses: actions/checkout@v2
  staging:
    name: Staging Deployment
    runs-on: ubuntu-latest
    if: ${{ github.ref == 'refs/heads/develop' }}
    environment:
        name: Staging
        url: https://staging.example.com/product
    steps:
      - uses: actions/checkout@v2

Installation

Use it Once

npx @allejo/gha-workflows

As a Dependency

npm install --save-dev @allejo/gha-workflows
# or
yarn add --dev @allejo/gha-workflows

CLI Usage

usage: gha-workflows.js [-h] [-v] [-c COMMENTS] [-s SOURCE] [-d DESTINATION]

A super simple script to manage building Workflows for GitHub Actions

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -c COMMENTS, --comments COMMENTS
                        Add a header comment
  -s SOURCE, --source SOURCE
                        The source directory YAML files or single YAML file that will be "compiled"
  -d DESTINATION, --destination DESTINATION
                        The output directory where "compiled" YAML files will be written to

• The SOURCE will be the file or folder where the "source" YAML files (i.e. those with anchors and references) are located.
• The DESTINATION file or folder will be where the compiled/flattened YAML file is written to. This should usually inside of .github/workflows/.
• The COMMENTS value, which accepts \n, will be comments added to the top of the outputted YAML files; useful for adding warnings not to edit a generated file.

Inside of package.json

In the spirit of JS stuffing literally everything into package.json, you can use the gha-workflows key to configure this utility.

{
  "name": "my-simple-app",
  // ...
  "gha-workflows": {
    "source": ".github/workflows-src",
    "destination": ".github/workflows",
    "comments": [
      "DO NOT EDIT MANUALLY. THIS FILE IS AUTOMATICALLY GENERATED.",
      "Edit the source files in `.github/workflows-src/`"
    ]
  }
}

• The comments key can be either a string with newlines, or an array of strings.