https://github.com/koki-develop/ghats
GitHub Actions with TypeScript
https://github.com/koki-develop/ghats
Last synced: 9 months ago
JSON representation
GitHub Actions with TypeScript
- Host: GitHub
- URL: https://github.com/koki-develop/ghats
- Owner: koki-develop
- License: mit
- Created: 2025-03-28T10:36:06.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-05-06T12:02:27.000Z (9 months ago)
- Last Synced: 2025-05-07T21:07:04.774Z (9 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/ghats
- Size: 571 KB
- Stars: 110
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Actions with TypeScript
[](https://www.npmjs.com/package/ghats)
[](https://github.com/koki-develop/ghats/actions/workflows/release-please.yml)
[](https://codecov.io/gh/koki-develop/ghats)
[](./LICENSE)
```ts
// .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
```console
$ npm install -D ghats
```
## Getting Started
Create workflow in `.github/workflows/*.ts` using the `ghats`.
```ts
// .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`.
```console
$ 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.
```sh
$ 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.
```ts
// .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.
```console
$ 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.
```json5
// 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](./LICENSE)