gat

The gat project is a tool to write your GitHub Actions workflows using TypeScript.

Maintaining YAML files is hard and if your project is big enough you will find yourself duplicating a lot of code between your workflows. With gat you can create reusable jobs and steps just using TypeScript objects and importing them in your workflow templates.

Why gat? The name is an acronym of "GitHub Actions Template Generator" without the last part because gat means "cat" in Catalan.

Installation

Install the main package and its dependencies using the following command:

npm i -D @factorialco/gat typescript tsx commander @swc/core

Usage

Writing a template

The gat CLI assumes that you have a index.ts file inside .github/templates. Let's create our first template:

// .github/templates/index.ts
import { Workflow } from "@factorialco/gat";

await new Workflow("My first workflow")
  .on("push")
  .addJob("test", {
    steps: [
      {
        uses: "actions/checkout@v3",
      },
      {
        uses: "actions/setup-node@v3",
      },
      {
        run: "npm test",
      },
    ],
  })
  .compile({ filePath: "my-first-workflow.yml" });

Notice that you need to call the compile() method at the end, passing an options object with the filePath of the generated GitHub Actions workflow.

Compiling your templates

You can build your templates running this command in your root folder:

npx gat build

Following the previous example, you should see now a file .github/workflows/my-first-workflow.yml like this:

# Workflow automatically generated by gat
# DO NOT CHANGE THIS FILE MANUALLY

name: My first workflow
on:
  push: null
jobs:
  test:
    runs-on: ubuntu-22.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm test

Notice that the job includes a few assumptions like the runs-on and timeout-minutes fields. You can change those when adding a new job.

Create your own workflow class

You can create factory functions that return pre-configured Workflow instances with shared settings. This avoids duplication across your templates:

// .github/templates/helpers.ts
import { Workflow } from "@factorialco/gat";

export function createWorkflow(name: string) {
  return new Workflow(name)
    .setEnv("NODE_ENV", "production")
    .on("push", { branches: ["main"] });
}

Then use it in your templates:

// .github/templates/index.ts
import { createWorkflow } from "./helpers";

await createWorkflow("Test")
  .addJob("test", {
    steps: [{ run: "npm test" }],
  })
  .compile({ filePath: "test.yml" });

await createWorkflow("Lint")
  .addJob("lint", {
    steps: [{ run: "npm run lint" }],
  })
  .compile({ filePath: "lint.yml" });

This way all your workflows share the same environment variables, triggers, and any other defaults you configure in the factory function.

Contributing

1. Fork the repository and clone it locally
2. Install dependencies: npm install
3. Run the tests: npm test
4. Make your changes and ensure tests pass
5. Submit a pull request

License

MIT