@factorialco/gat 3.5.0 → 3.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Factorial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="gat.png" width="200" />
+</p>
+
 # 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**.
@@ -24,7 +28,7 @@ The `gat` CLI assumes that you have a `index.ts` file inside `.github/templates`
 // .github/templates/index.ts
 import { Workflow } from "@factorialco/gat";
 
-new Workflow("My first workflow")
+await new Workflow("My first workflow")
   .on("push")
   .addJob("test", {
     steps: [
@@ -39,10 +43,10 @@ new Workflow("My first workflow")
       },
     ],
   })
-  .compile("my-first-workflow.yml");
+  .compile({ filePath: "my-first-workflow.yml" });
 ```
 
-Notice that you need to call the `compile()` method at the end, passing the file name of the generated Github Actions workflow.
+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
 
@@ -75,11 +79,47 @@ Notice that the job includes a few assumptions like the `runs-on` and `timeout-m
 
 ### Create your own workflow class
 
-TODO
+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
 
-TODO
+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
 

package/dist/job.d.ts

@@ -8,6 +8,7 @@ export interface Matrix {
         options: Array<string | number | boolean>;
     }>;
     extra?: Array<Record<string, string | number | boolean>>;
+    maxParallel?: number;
 }
 export interface Service {
     image: string;

package/dist/workflow.d.ts

@@ -23,11 +23,13 @@ export declare class Workflow<JobStep extends Step = Step, Runner extends Runner
     defaultOptions: DefaultOptions | null;
     env: EnvVar[];
     concurrencyGroup?: ConcurrencyGroup | null;
+    runName?: string;
     constructor(name: string);
     on<T extends EventName>(name: T, options?: EventOptions<T>): this;
     addDefaults(options: DefaultOptions): this;
     addJob<T extends string>(name: StringWithNoSpaces<T>, options: StepsJobOptions<JobStep, Runner, JobName> | UsesJobOptions<JobName>): Workflow<JobStep, Runner, JobName | T>;
     setEnv(name: string, value: string): this;
+    setRunName(runName: string): this;
     setConcurrencyGroup(concurrencyGroup: ConcurrencyGroup | null): this;
     defaultRunner(): string;
     compile(compileOptions?: WorkflowCompileOptions): Promise<string | void>;

package/dist/workflow.js

@@ -41,6 +41,10 @@ class Workflow {
         this.env = [...this.env, { name, value }];
         return this;
     }
+    setRunName(runName) {
+        this.runName = runName;
+        return this;
+    }
     setConcurrencyGroup(concurrencyGroup) {
         this.concurrencyGroup = concurrencyGroup;
         return this;
@@ -51,6 +55,7 @@ class Workflow {
     async compile(compileOptions = {}) {
         const result = {
             name: this.name,
+            "run-name": this.runName,
             on: Object.fromEntries(this.events.map(({ name, options }) => [
                 name,
                 options ? options : null,
@@ -107,6 +112,9 @@ class Workflow {
                         strategy: matrix
                             ? {
                                 "fail-fast": false,
+                                "max-parallel": typeof matrix !== "string" && matrix.maxParallel != null
+                                    ? matrix.maxParallel
+                                    : undefined,
                                 matrix: typeof matrix === "string"
                                     ? matrix
                                     : {

package/dist/workflow.spec.js

@@ -126,6 +126,26 @@ const workflow_1 = require("./workflow");
         });
         (0, vitest_1.expect)(await workflow.compile()).toMatchSnapshot();
     });
+    (0, vitest_1.it)("allows a job matrix with max-parallel", async () => {
+        const workflow = new workflow_1.Workflow("Matrix with max parallel");
+        workflow.on("push").addJob("job1", {
+            matrix: {
+                elements: [
+                    {
+                        id: "food",
+                        options: ["🍕", "🍔", "🌮"],
+                    },
+                ],
+                maxParallel: 2,
+            },
+            steps: [
+                {
+                    run: "echo ${{ matrix.food }}",
+                },
+            ],
+        });
+        (0, vitest_1.expect)(await workflow.compile()).toMatchSnapshot();
+    });
     (0, vitest_1.it)("allows uses steps", async () => {
         const workflow = new workflow_1.Workflow("Uses steps");
         workflow
@@ -291,6 +311,19 @@ exit 0`,
             },
         })).toMatchSnapshot();
     });
+    (0, vitest_1.it)("supports a workflow-level run name", async () => {
+        const workflow = new workflow_1.Workflow("With run name")
+            .setRunName("Preview ${{ inputs.domain }} #${{ inputs.environmentIndex }}")
+            .on("workflow_dispatch", {
+            inputs: {
+                domain: { description: "A domain", required: true },
+            },
+        })
+            .addJob("job1", {
+            steps: [{ name: "Do something", run: "exit 0" }],
+        });
+        (0, vitest_1.expect)(await workflow.compile()).toMatchSnapshot();
+    });
     (0, vitest_1.it)("allows setting environment on a job", async () => {
         const workflow = new workflow_1.Workflow("Job Environment");
         workflow.on("push").addJob("job1", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factorialco/gat",
-  "version": "3.5.0",
+  "version": "3.10.1",
   "description": "Write your GitHub Actions workflows using TypeScript",
   "bin": {
     "gat": "dist/cli.js"
@@ -22,7 +22,7 @@
     "format:check": "prettier --check ."
   },
   "author": "David Morcillo <david.morcillo@factorial.co>",
-  "license": "ISC",
+  "license": "MIT",
   "devDependencies": {
     "@swc/core": "^1.3.14",
     "@types/js-yaml": "^4.0.5",