@jlarky/gha-ts

gha-ts

A TypeScript library for writing GitHub Actions workflows and rendering them to YAML.

• Extremely lean core, gha-ts has 0 dependencies, you provide your own yaml serializer (or just use JSON.stringify, because any valid JSON is also valid YAML)
• No typescript overhead. Github will only use generated YAML files, so it won't see the difference. You use typescript just on your machine and heck, it doesn't even has to be typescript (see javascript example in Examples section)!
• For quicker onboarding we provide CLI to convert all of your existing workflows to TypeScript (or start with one file!).

It's easy to start with gha-ts, but for production-ready uses I would strongly recommend checking out gha-ts-enterprise-node example, that includes things like build/watch scripts, action version locking, linting of your workflows and an example of a CI job that checks that generated YAML files are in sync with the source.

Install

If using Bun:

bunx jsr add -D @jlarky/gha-ts # or bun add -D @jlarky/gha-ts

If using Node.js:

npx nypm add -D @jlarky/gha-ts yaml # or npx jsr add -D @jlarky/gha-ts

Notes:

• Bun users will import YAML from bun and node users will use yaml from npm.
• This example is using Bun, but you can find other examples in the examples directory.

Quickstart

Create a workflow module at .github/workflows/example-bun.main.ts (when using Bun):

#!/usr/bin/env bun
import { YAML } from "bun";
import { workflow } from "@jlarky/gha-ts/workflow-types";
import { checkout } from "@jlarky/gha-ts/actions";
import { generateWorkflow } from "@jlarky/gha-ts/cli";

const wf = workflow({
  name: "Example workflow",
  on: {
    push: { branches: ["main"] },
    pull_request: {},
  },
  jobs: {
    exampleJob: {
      "runs-on": "ubuntu-latest",
      steps: [
        checkout({ "fetch-depth": 0 }),
        { name: "Test", run: "echo 'Hello, world!'" },
      ],
    },
  },
});

await generateWorkflow(wf, YAML.stringify, import.meta.url);

Examples

• Look at the .github/workflows directory for workflow examples.
• Additional usage examples: examples/.
• Hello world (Bun)
• Hello world (Node.js)
• Hello world (Javascript)
• Hello world (Deno)
• Enterprise (Node.js) - great example of using gha-ts "for real".

License

MIT

Alternatives

• actions-toolkit
• ghats
• github-actions-typescript
• github-actions-typing
• github-actions-wac
• github-actions-workflow-ts
• workflow-ts

Non JavaScript/TypeScript:

• dagger
• gh-workflow (Rust)
• github-workflows-kt (Kotlin)
• kotlin-github-actions-dsl (Kotlin)
• pkl-gha (Pkl)
• sbt-github-actions (Scala)