Skip to content

dsherret/gagen

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

78 Commits
.github/workflows
.github/workflows
 
 
scripts
scripts
 
 
src
src
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
deno.json
deno.json
 
 
deno.lock
deno.lock
 
 

Repository files navigation

gagen

JSR npm Version

Generate complex GitHub Actions YAML files using a declarative API.

Gagen lets you define workflows in TypeScript with a fluent, declarative API that automatically resolves step ordering and propagates conditions. The condition propagation helps skip unnecessary setup steps and eliminates needing to repeat condition text over and over again.

Additionally, gagen automatically pins dependencies in the output so your initial code is more easily maintainable.

Basic usage

// .github/workflows/ci.ts
import { conditions, step, workflow } from "gagen";

const checkout = step({
  uses: "actions/checkout@v6",
});

const test = step.dependsOn(checkout)({
  name: "Test",
  run: "cargo test",
});

const installDeno = step({
  uses: "denoland/setup-deno@v2",
});

const lint = step
  .dependsOn(checkout)
  // this condition gets propagated to installDeno, but not checkout
  .if(conditions.isBranch("main").not())(
    {
      name: "Clippy",
      run: "cargo clippy",
    },
    step.dependsOn(installDeno)({
      name: "Deno Lint",
      run: "deno lint",
    }),
  );

// only specify the leaf steps — the other steps are pulled in automatically
workflow({
  name: "ci",
  on: ["push", "pull_request"],
  jobs: [{
    id: "build",
    runsOn: "ubuntu-latest",
    steps: [lint, test],
  }],
}).writeOrLint({
  filePath: new URL("./ci.generated.yml", import.meta.url),
  header: "# GENERATED BY ./ci.ts -- DO NOT DIRECTLY EDIT",
});

Generate via the gagen cli:

# or alternatively run the script directly
npx gagen

This generates a ci.generated.yml with steps in the correct order and figures out that it should only install deno when the lint step should be run and it defers that step only until it's necessary.

# GENERATED BY ./ci.ts -- DO NOT DIRECTLY EDIT

name: ci
on:
  - push
  - pull_request
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Clippy
        if: github.ref != 'refs/heads/main'
        run: cargo clippy
      - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2
        if: github.ref != 'refs/heads/main'
      - name: Deno Lint
        if: github.ref != 'refs/heads/main'
        run: deno lint
      - name: Test
        run: cargo test

When run normally, this writes ci.generated.yml. When run with --lint, it reads the existing file and compares the parsed YAML — exiting with a non-zero code if they differ. This lets you add a CI step to verify the generated file is up to date:

const lintStep = step({
  name: "Lint CI generation",
  // alternatively, use `npx gagen --lint` to lint all the files
  // in the `.github/workflows` folder
  run: "./.github/workflows/ci.ts --lint",
});

CLI

If you store your generations scripts beside your .yml files in the .github/workflows folder, then you can automatically run all these scripts by using the gagen binary:

# generate the output
npx gagen

# lint the output
npx gagen --lint

# pull version bumps from generated yaml back into the source scripts
# (useful after dependabot updates a .generated.yml)
npx gagen --pull-versions

The requires your scripts to use the writeOrLint function.

--pull-versions

Dependabot updates the inline version comment on each uses: line of the generated YAML (e.g. actions/checkout@<new-hash> # v7). The source script still reads v6, so the next regeneration would revert the bump. Running npx gagen --pull-versions scans every YAML in .github/workflows, collects the current version for each action, then rewrites "owner/repo@<old>" literals in the script files to match. The YAML is already up to date, so no regeneration is needed.

Limitations:

  • Only literal "owner/repo@ref" strings (double or single quoted) are rewritten. Template literals with substitutions and computed uses values are left alone.
  • If the same action appears in multiple YAML files with different versions, it is reported as a conflict and skipped — resolve it manually.

Dependency pinning—the output is a lockfile

By default, writeOrLint pins action references to their resolved commit hashes then stores that hash value locked in the output.

For example, if you write the following step in a workflow:

step({
  uses: "actions/checkout@v6",
})

It will output:

steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6

The inline comment records the original ref so gagen can re-resolve it when you run with --update-pins.

Then the next time it runs, it will read the output to get a locked set of dependencies.

To force re-resolving all pins, run with the --update-pins flag:

./ci.ts --update-pins

Pinning can be disabled by setting pinDeps to false:

wf.writeOrLint({ filePath, pinDeps: false });

A custom resolver can also be provided:

wf.writeOrLint({
  filePath,
  pinDeps: { resolve: (owner, repo, ref) => lookupHash(owner, repo, ref) },
});

Conditions

Build type-safe GitHub Actions expressions with a fluent API:

import { expr } from "gagen";

const ref = expr("github.ref");
const os = expr("matrix.os");

// simple comparisons
ref.equals("refs/heads/main");
// => github.ref == 'refs/heads/main'

ref.startsWith("refs/tags/").not();
// => !startsWith(github.ref, 'refs/tags/')

// compose with .and() / .or()
os.equals("linux").and(ref.startsWith("refs/tags/"));
// => matrix.os == 'linux' && startsWith(github.ref, 'refs/tags/')

// use on steps
const deploy = step.dependsOn(build).if(
  ref.equals("refs/heads/main").and(os.equals("linux")),
)({
  name: "Deploy",
  run: "deploy.sh",
});

Common conditions

The conditions object provides composable helpers for common GitHub Actions patterns:

import { conditions } from "gagen";

const { status, isTag, isBranch, isEvent } = conditions;

// status check functions
status.always(); // always()
status.failure(); // failure()
status.success(); // success()
status.cancelled(); // cancelled()

// ref checks
isTag(); // startsWith(github.ref, 'refs/tags/')
isTag("v1.0.0"); // github.ref == 'refs/tags/v1.0.0'
isBranch("main"); // github.ref == 'refs/heads/main'

// event checks
isEvent("push"); // github.event_name == 'push'
isEvent("pull_request"); // github.event_name == 'pull_request'

// compose freely with .and() / .or() / .not()
const deploy = step.dependsOn(build).if(isBranch("main").and(isEvent("push")))({
  name: "Deploy",
  run: "deploy.sh",
});

const cleanup = step.dependsOn(build).if(status.always())({
  name: "Cleanup",
  run: "rm -rf dist",
});

Ternary expressions

Build GitHub Actions ternary expressions (condition && trueVal || falseVal) with a fluent .then().else() chain:

const os = expr("matrix.os");

// simple ternary
const runner = os.equals("linux").then("ubuntu-latest").else("macos-latest");
// => matrix.os == 'linux' && 'ubuntu-latest' || 'macos-latest'

// multi-branch with elseIf
const runner = os.equals("linux").then("ubuntu-latest")
  .elseIf(os.equals("macos")).then("macos-latest")
  .else("windows-latest");
// => matrix.os == 'linux' && 'ubuntu-latest' || matrix.os == 'macos' && 'macos-latest' || 'windows-latest'

// use in job config
workflow({
  // ...,
  jobs: [
    { id: "build", runsOn: runner, steps: [test] },
  ],
});

Values can be strings, numbers, booleans, or ExpressionValue references. Conditions with || are automatically parenthesized to preserve correct evaluation order.

Condition propagation

Conditions on leaf steps automatically propagate backward to their dependencies. This avoids running expensive setup steps when they aren't needed:

const checkout = step({ uses: "actions/checkout@v6" });
const build = step.dependsOn(checkout)({ run: "cargo build" });
const test = step.dependsOn(build).if(expr("matrix.job").equals("test"))({
  run: "cargo test",
});

// only test is passed — checkout and build inherit its condition
workflow({
  ...,
  jobs: [
    { id: "test", runsOn: "ubuntu-latest", steps: [test] },
  ],
});
// all three steps get: if: matrix.job == 'test'

When multiple leaf steps have different conditions, dependencies get the OR of those conditions:

const test = step.dependsOn(checkout).if(jobExpr.equals("test"))({
  run: "cargo test",
});
const bench = step.dependsOn(checkout).if(jobExpr.equals("bench"))({
  run: "cargo bench",
});

workflow({
  ...,
  jobs: [
    { id: "test", runsOn: "ubuntu-latest", steps: [test, bench] },
  ],
});
// checkout gets: if: matrix.job == 'test' || matrix.job == 'bench'

Step outputs and job dependencies

Steps can declare outputs. When a job references another job's outputs, the needs dependency is inferred automatically.

import { job, step, workflow } from "gagen";

const checkStep = step({
  id: "check",
  name: "Check if draft",
  run: `echo 'skip=true' >> $GITHUB_OUTPUT`,
  outputs: ["skip"],
});

// use job() when you need a handle for cross-job references
const preBuild = job("pre_build", {
  runsOn: "ubuntu-latest",
  steps: [checkStep],
  outputs: { skip: checkStep.outputs.skip },
});

// preBuild.outputs.skip is an ExpressionValue — using it in the `if`
// automatically adds needs: [pre_build] to this job
const wf = workflow({
  name: "ci",
  on: ["push", "pull_request"],
  jobs: [
    preBuild,
    {
      id: "build",
      runsOn: "ubuntu-latest",
      if: preBuild.outputs.skip.notEquals("true"),
      steps: [buildStep],
    },
  ],
});

Diamond dependencies

Steps shared across multiple dependency chains are deduplicated and topologically sorted:

const checkout = step({ name: "Checkout", uses: "actions/checkout@v6" });
const buildA = step.dependsOn(checkout)({ name: "Build A", run: "make a" });
const buildB = step.dependsOn(checkout)({ name: "Build B", run: "make b" });
const integrate = step.dependsOn(buildA, buildB)({
  name: "Integrate",
  run: "make all",
});

workflow({
  ...,
  jobs: [
    { id: "ci", runsOn: "ubuntu-latest", steps: [integrate] },
  ],
});
// resolves to: checkout → buildA → buildB → integrate
// checkout appears only once

Ordering constraints

Use comesAfter() to control step ordering without creating a dependency. Unlike dependsOn(), this does not pull in the step — it only ensures ordering when both steps are present in the same job:

const setupDeno = step({
  uses: "denoland/setup-deno@v2",
  with: { "deno-version": "canary" },
});

// ensure checkout runs after setupDeno, without making checkout depend on it
const checkout = step.comesAfter(setupDeno)({ uses: "actions/checkout@v6" });
const build = step.dependsOn(checkout)({ run: "cargo build" });
const lint = step.dependsOn(setupDeno, checkout)({ run: "deno lint" });

workflow({
  ...,
  jobs: [
    { id: "ci", runsOn: "ubuntu-latest", steps: [build, lint] },
  ],
});
// resolves to: setupDeno → checkout → build → lint

If the constraint conflicts with existing dependencies (creating a cycle), the library throws with the cycle path:

Error: Cycle detected in step ordering: A → B → A

Typed matrix

defineMatrix() gives you typed access to matrix values:

import { workflow, defineMatrix } from "gagen";

const matrix = defineMatrix({
  include: [
    { runner: "ubuntu-latest" },
    { runner: "macos-latest" },
  ],
});

matrix.runner; // ExpressionValue("matrix.runner") — autocompletes
matrix.foo; // TypeScript error — not a matrix key

workflow({
  ...,
  jobs: [
    {
      id: "build",
      runsOn: matrix.runner,
      strategy: { matrix },
      steps: [test],
    },
  ],
});

Artifacts

Link upload and download artifact steps across jobs with automatic needs inference:

import { artifact, step, workflow } from "gagen";

const buildOutput = artifact("build-output");

const wf = workflow({
  name: "CI",
  on: ["push", "pull_request"],
  jobs: [
    {
      id: "build",
      runsOn: "ubuntu-latest",
      steps: [
        step({ name: "Build", run: "make build" }),
        buildOutput.upload({ path: "dist/" }),
      ],
    },
    // `needs: [build]` is inferred automatically from the artifact link
    {
      id: "deploy",
      runsOn: "ubuntu-latest",
      steps: [
        buildOutput.download({ dirPath: "output/" }),
        {
          name: "Deploy",
          run: "make deploy",
        },
      ],
    },
  ],
});

Upload requires path (a glob pattern for files to upload). Download accepts an optional dirPath (the directory to download into).

The artifact version and default retention days can be configured:

const buildOutput = artifact("build-output", {
  version: "v3",
  retentionDays: 5,
});

About

Generate complex GitHub Actions YAML files using a declarative API.

Resources

Readme

License

MIT license
Activity

Stars

143 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 31

0.5.0 Latest
Apr 23, 2026
+ 30 releases

Packages

 
 
 

Contributors

Languages