GitHub Actions with TypeScript

Warning

This is an experimental project. Please use with caution in production environments.

// .github/workflows/hello.ts
import { Workflow, Job } from "ghats";

const workflow = new Workflow("Hello", {
  on: "push",
});

workflow.addJob(
  new Job("hello", {
    runsOn: "ubuntu-latest",
  })
    .uses("actions/checkout@v4")
    .run("echo 'Hello, world!'"),
);

export default workflow;

Installation

$ npm install -D ghats

Getting Started

Create workflow in .github/workflows/*.ts using the ghats.

// .github/workflows/hello.ts
import { Workflow, Job } from "ghats";

const workflow = new Workflow("Hello", {
  on: "push",
});

workflow.addJob(
  new Job("hello", {
    runsOn: "ubuntu-latest",
  })
    .uses("actions/checkout@v4")
    .run("echo 'Hello, world!'"),
);

export default workflow; // NOTE: don't forget this line

Run ghats build to build GitHub Actions Workflow files as .github/workflows/*.yml.

$ npx ghats build

That's all you need to know for basic usage!

Type Support for Remote Actions

Run the ghats install command with the target action specified.

$ npx ghats install actions/checkout

Then you can import the action function from ghats.
The action function provides type support for installed actions and their inputs.

// .github/workflows/hello.ts
import { Workflow, Job, action } from "ghats";

// ...

workflow.addJob(
  new Job("hello", { /* ... */ })
    .uses(
      // ↓↓ Like this! ↓↓
      action("actions/checkout", {
        with: { "persist-credentials": "false" },
      }),
    )
    // ...
);

// ...

Installed actions are recorded in .github/workflows/action.json and .github/workflows/actions-lock.json.

Files Ignored During Build

By default, ghats build builds all .github/workflows/*.ts files, but ignores files that start with _ (e.g. .github/workflows/_helpers.ts).
It's recommended to write common utilities and non-workflow code in these ignored files.

Configuring GitHub API Token

The ghats install command uses the GitHub API internally.
If you're using remote actions from private repositories or want to pass a GitHub API token to avoid rate limits, set the GITHUB_TOKEN environment variable.

$ GITHUB_TOKEN="<YOUR_GITHUB_TOKEN>" npx ghats install

Updating actions.json and actions-lock.json with Renovate

ghats records the versions of installed remote actions in .github/workflows/actions.json and .github/workflows/actions-lock.json.
To automatically update these remote action versions with Renovate, add "github>koki-develop/ghats" to the extends in your configuration file.

// renovate.json
{
  "extends": ["github>koki-develop/ghats"]
}

Note

Note that after updating actions.json and actions-lock.json, you need to rebuild your workflows.

License

MIT