npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@factorialco/gat

v3.13.0

Published

Write your GitHub Actions workflows using TypeScript

Readme

gat Build npm version

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:

| Option | Default | Description | | ----------------------- | ------- | -------------------------------------------------------------------------- | | templates | | Map of file names in .github/workflows to Workflow instances. | | lockFilePath | none | Path to a gat-lock.json file. Without it, gat writes the refs unchanged. | | writeLockFile | false | Resolve every action tag to a commit SHA and rewrite the lock file. | | failOnUnlockedActions | false | Stop when a step uses an action that has no entry in the lock file. |

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