Action Starter

A minimal template for building a JavaScript GitHub Action.

Getting Started

Create a new repository from this template on GitHub using this link.

Or clone it locally and point it at your own remote.

Setup

Install pnpm, then install dependencies:

pnpm install

Install Lefthook, then register the pre-commit hooks:

lefthook install

Customizing the Action

action.yml

Update the action's name, description, branding, and inputs/outputs to match what your action does.

src/action.ts and src/main.ts

src/action.ts holds your action logic as an exported async function. src/main.ts is the entry point — it calls that function and handles errors.

Use ghakit for anything GitHub Actions-related — reading inputs, writing outputs, logging, spawning processes, and more.

// src/action.ts
import { getInput } from "ghakit/io";

export async function myAction() {
  const input = getInput("my-input");
  // ... your action logic ...
}

LICENSE

The template ships with the Unlicense (public domain). Replace it with the license you want, or leave it as-is.

Development Workflow

Write your code in src/. When you're ready, just commit — the pre-commit hook will automatically:

1. Install dependencies
2. Format code (Prettier)
3. Fix lint issues (ESLint)
4. Type-check (TypeScript)
5. Build the bundle (dist/main.bundle.mjs)

If the hook reports errors, fix them and commit again. The dist/ folder must be committed — it's what GitHub Actions runs.

Testing

Add test files alongside source files as *.test.ts. Run all tests with:

pnpm test

100% code coverage is enforced. Tests use Vitest.

CI

.github/workflows/ci.yaml runs two jobs on every push and pull request:

• check — validates the pre-commit hook and runs tests
• test — runs the real action on Ubuntu, macOS, and Windows

Update the test job to exercise your action's actual inputs and verify its outputs.

Releasing

Tag a release on GitHub:

git tag v1.0.0
git push origin v1.0.0

Then create a GitHub Release from that tag. To make the action discoverable, publish it to the GitHub Marketplace from the release page.