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.

Compiling many templates

compileTemplates compiles a map of output file names to workflows in one call:

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

import Build from "./build";
import Deploy from "./deploy";

compileTemplates({
  templates: {
    "build.yml": Build,
    "deploy.yml": Deploy,
  },
});

It accepts these options:

writeLockFile and failOnUnlockedActions need a lockFilePath.

Pinning actions

A tag such as actions/checkout@v4 can move to a different commit. To make sure that a workflow always runs the code you reviewed, pin every action to a commit. You can do this in two ways. Use one of them, not both.

Option A: gat lock file

gat replaces each action tag with a commit SHA when it writes the workflow.

1. Add lockFilePath and writeLockFile to compileTemplates, and read writeLockFile from an environment variable:

   compileTemplates({
     templates,
     lockFilePath: ".github/templates/gat-lock.json",
     writeLockFile: process.env.GAT_WRITE_LOCK_FILE === "true",
     failOnUnlockedActions: true,
   });
   

2. Run the build once with GAT_WRITE_LOCK_FILE=true and a GITHUB_TOKEN. gat uses the GitHub API to resolve each tag and writes gat-lock.json:

   {
     "actions/[email protected]": "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683"
   }
   

3. Commit the lock file. Later builds read it and write uses: actions/checkout@11bd719... into the workflow.

With failOnUnlockedActions: true, the build stops when a step uses an action that has no entry. Without it, gat writes the tag, and that step is not pinned. SHA refs, local ./ actions and docker:// images are not checked.

The lock file has these limits:

• A write resolves every action that the templates use and rewrites the whole file. It can move other actions to new commits and remove entries that you added by hand. Review the full diff of gat-lock.json.
• Only steps are pinned. Actions that an action calls (transitive dependencies) and reusable workflows are not pinned.

Option B: GitHub workflow lockfile

GitHub can pin actions with workflow dependency lockfiles. The gh actions-lock extension writes .github/workflows/actions.lock, and GitHub Actions runs the locked commit. It also pins transitive dependencies and checks that the action repository did not change owner.

1. Do not set lockFilePath. gat then writes the tags from your templates.

2. Install the extension: gh extension install github/gh-actions-lock.

3. After each build, update the lockfile from the repository root:

   npx gat build
   gh actions-lock --no-narrow
   

   Always use --no-narrow. Without it, the tool rewrites uses: lines in the workflows, for example @v4 to @v4.2.2. The workflows then no longer match the templates, and the next build undoes the change.

4. Commit actions.lock with the workflows. Do not edit it by hand.

5. In CI, check the lockfile on each pull request that changes a workflow. Pin the extension version:

   - run: gh extension install github/gh-actions-lock --pin v0.2.0
     env:
       GH_TOKEN: ${{ github.token }}
   - run: gh actions-lock --verify
     env:
       GH_TOKEN: ${{ github.token }}
   

   --verify fails when a workflow or an action has no entry, and when a locked commit is no longer valid.

The GitHub lockfile is in public preview, and its format can change. If the lockfile is not valid, GitHub ignores it and runs the tags, so the CI check is important.

Do not combine the options

With both options, the workflows contain SHAs. gh actions-lock warns about each SHA ref. Without --no-narrow, it also rewrites the SHAs to tags. Choose one option for the repository.

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