Declare your GitHub Workflows in TypeScript or JavaScript instead of YAML!

1. I replaced npm with pnpm for faster installing and CI.
2. I replaced ts-node with tsx for better DX.
3. I added helpers for your workflows to the package.

!!! The examples are not updated yet !!!

Github Workflow Generator is a library that enables you to write templates for your GitHub Workflows in JavaScript or Typescript and use that code to generate valid GitHub Workflows as YAML files.

Admittedly, that's a long and complex sentence, so let's show a quick example instead:

const workflow: Workflow = {
  name: "Simple Workflow",
  on: {
    push: {},
  },
  jobs: {
    echo: {
      name: "Echo",
      "runs-on": "macos-latest",
      steps: [
        {
          name: "Echoing!",
          run: 'echo "Hello World!"',
        },
      ],
    },
  },
};

This will generate this Yaml file:

name: 'Simple Workflow'
'on':
  push: {}
jobs:
  echo:
    name: 'Echo'
    runs-on: 'macos-latest'
    steps:
      - name: 'Echoing!'
        run: 'echo "Hello World!"'

This Workflow will run on every new push to any branch, with a single job named "Echo" that runs on a macOS 10.15 runner that prints out "Hello World".

If your Workflow is as simple as the Workflow listed above, you likely wouldn't want or need this library. However, if you have multiple Workflows that need to share steps, this library becomes very useful.

Imagine:

const basicSetup: Step[] = [
  {
    name: "Checkout project",
    uses: 'actions/checkout@v2',
  },
  {
    name: "Install project dependencies",
    run: "npm ci",
  },
];

const buildAppWorkflow: Workflow = {
  name: "Build The App",
  on: {
    push: {},
  },
  jobs: {
    echo: {
      name: "Build",
      "runs-on": "macos-latest",
      steps: [
        ...basicSetup,
        {
          name: "Build",
          run: 'npm run build',
        },
      ],
    },
  },
};

const buildLibraryWorkflow: Workflow = {
  name: "Build The Library",
  on: {
    push: {
        branches: ['special-branch']
    },
  },
  jobs: {
    echo: {
      name: "Build",
      "runs-on": "ubuntu-latest",
      steps: [
        ...basicSetup,
        {
          name: "Build",
          run: 'npm run build-lib',
        },
      ],
    },
  },
};

This is only a small taste as well. You can share whole jobs, if needed.

Since everything is strongly-typed using TypeScript, you can also enforce that every Workflow uses the same version of your various actions, and update all of your actions at the same time. See the "using versions" example here.

Good question! Since this library doesn't currently exhaustively cover everything you can do in a Workflow, the type system has been purposefully made to be easily extensible, where possible. Take a look at the "adding or modifying fields" example for how to do that.

Yup! Consider the typings just a bit of syntactical sugar; this library works just fine with pure JavaScript as well.

First, let's install it:

npm install --save-dev @wardellbagby/gh-workflow-gen

Next, let's create our first Workflow:

import { Workflow } from '@wardellbagby/gh-workflow-gen';

export const myWorkflow: Workflow = {
    // TODO fill this in.
}

Now, we need to create a simple script to import these Workflows and write them to a file.

import { myWorkflow } from "myWorkflowFile";
import { writeWorkflow } from "@wardellbagby/gh-workflow-gen";

writeWorkflow(myWorkflow);

Lastly, we simply run the script you just created in the root of your project folder.

cd path/to/my/project
node generate_workflows.js

This will create the workflows directory inside your existing .github directory with the generated Workflows saved.

Yes! This project uses itself, and as a part of its setup, it uses script created in the last step above and runs as a pre-commit hook using Husky. If you'd like that as an example, check this out.