🛕 ghat

Reuse GitHub Actions workflows across repositories

On first run,

ghat

env

1. Write workflows once, use them in any repository
2. Update your workflows without copy-pasting YAML
3. Preserve local

   env

   variables
4. Customize workflows before importing them

The good parts:

• ghat

  does not run every time on your CI

• ghat

  doesn't have to be a dependency of your project

• ghat

  is node-based, but can install any type of workflows
• Workflow changes need to be committed by the user, so you don't have to worry about it suddenly breaking "because of a dependency"

Requirements:

• git
• npm or yarn (you can use

  npx ghat ...

  or

  yarn dlx ghat ...

  to run it without installing it)
• a writable

  ~/.degit

  cache folder as required by degit

Usage

ghat

$ ghat --help

  Description
    Reuse GitHub Actions workflows across repositories
  Usage
    $ ghat  [options]
  Options
    --exclude        Any part of the YAML file to be removed (can be repeated)
    --set            Value to add (can be repeated). The value is interpreted as YAML/JSON. Writing JSON on the CLI is tricky, so you might want to wrap the whole flag value
    -v, --version    Displays current version
    -h, --help       Displays this message
  Examples
    $ ghat fregante/ghatemplates/node
    $ ghat fregante/ghatemplates/node --exclude jobs.Build --exclude jobs.Test
    $ ghat fregante/ghatemplates/node --set on=push
    $ ghat fregante/ghatemplates/node --set 'jobs.Test.container=node:12.15'
    $ ghat fregante/ghatemplates/node-multi --set jobs.build.strategy.matrix.node-version=[8.x,10.x]
    $ ghat fregante/ghatemplates/node/build.yml

Fetch repo

If you provide a

user/repo

ghat

*.yml

*.yaml

.github/workflows

npx ghat fregante/ghat
# Copies *.yml OR .github/workflows/*.yml

Fetch whole folder

npx ghat fregante/ghatemplates/node
# Copies node/*.yml into the local .github/workflows. It's NOT recursive

Fetch specific file

npx ghat fregante/ghatemplates/node/ci.yml
# Copies node/ci.yml into the local .github/workflows/ci.yml

Customization

Exclude properties

You can exclude any property from the template by using the

--exclude 

• path

  is parsed by dot-prop, so refer to its documentation.

--exclude on.schedule

Set properties

You can set/overwrite any value with the

--set =

• path

  is parsed by dot-prop, so refer to its documentation.

• value

  is a YAML/JSON value passed directly to the YAML parser.

Note: writing JSON on the command line is a little tricky, so if you're running into errors, try wrapping the whole flag value into a string, for example:

--set 'on.schedule=[{"cron": "42 17 * * 4"}]'

env

object

When you fetch a workflow that already exists locally, the local file will be overridden, except for the top-level

env

Local file

env:
  ADJECTIVE: cool

DO NOT EDIT BELOW - use npx ghat fregante/workflows/demo
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo My workflow is $ADJECTIVE

Template file

env:
  ADJECTIVE: the default

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo This new workflow is "$ADJECTIVE" since it was updated

Updated local file

Only the top-level

env

env:
  ADJECTIVE: cool

DO NOT EDIT BELOW - use npx ghat fregante/workflows/demo
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo This new workflow is "$ADJECTIVE" since it was updated

What’s ghat?

GitHub Actions Templating

I won’t pretend to know exactly what a Ghat is, but you should know check them out, they’re beautiful. 🇮🇳

License

MIT © Federico Brigante