gat

KO | EN

gitlite — search

#python #hacktoberfest #typescript #llm #go #android #machine-learning #rust #deep-learning #docker #awesome-list #pytorch #security #open-source

(★ 15)

A tool to write your GitHub Actions workflows using TypeScript

gat Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# gat ![Build](https://github.com/factorialco/gat/actions/workflows/build.yml/badge.svg?branch=main) [![npm version](https://badge.fury.io/js/@factorialco%2Fgat.svg)](https://badge.fury.io/js/@factorialco%2Fgat)

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:

```bash
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:

```ts
// .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:

```bash
npx gat build
```

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

```yaml
# 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:

```ts
// .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:

```ts
// .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

gat

gat Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

gat

gat Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README