A zero-config build tool for creating GitHub Actions from TypeScript. Bundles with @vercel/ncc, validates action.yml against GitHub's schema, and outputs production-ready Node.js 24 actions.
npm install @savvy-web/github-action-builderA zero-config build tool for creating GitHub Actions from TypeScript source
code. Bundles your action with @vercel/ncc,
validates action.yml against GitHub's official schema, and outputs
production-ready Node.js 24 actions.
- Zero-config - Auto-detects entry points from src/main.ts, src/pre.ts,
src/post.ts
- Node.js 24 - Builds modern ESM actions for the latest GitHub Actions
runtime
- Schema validation - Validates action.yml against GitHub's official
metadata specification
- Single-file bundles - All dependencies inlined using @vercel/ncc
- CI-aware - Strict validation in CI, warnings-only locally
Create a new GitHub Action project with a single command:
``bash`
npx @savvy-web/github-action-builder init my-action
cd my-action
npm install
npm run build
That's it! Your action is built and ready. The init command generates a
complete project:
`text`
my-action/
├── src/
│ ├── main.ts # Main action entry point
│ ├── pre.ts # Pre-action hook
│ └── post.ts # Post-action cleanup
├── action.yml # GitHub Action metadata
├── action.config.ts # Build configuration
├── package.json # Dependencies and scripts
└── tsconfig.json # TypeScript configuration
Edit src/main.ts with your action logic, then rebuild with npm run build.dist/main.js
Your bundled action is in , ready to commit and use.
Create a new GitHub Action project:
`bash`
npx @savvy-web/github-action-builder init my-action
Bundle all entry points into dist/:
`bash`
npm run buildor directly:
npx @savvy-web/github-action-builder build
Check your action.yml and configuration without building:
`bash`
npm run validateor directly:
npx @savvy-web/github-action-builder validate
The builder expects this structure:
`text`
my-action/
├── src/
│ ├── main.ts # Required - main action entry point
│ ├── pre.ts # Optional - runs before main
│ └── post.ts # Optional - runs after main (cleanup)
├── action.yml # GitHub Action metadata (runs.using: "node24")
├── action.config.ts # Optional configuration
└── package.json
Customize action.config.ts for your project:
`typescript
import { GitHubAction } from "@savvy-web/github-action-builder";
export default GitHubAction.create({
entries: {
main: "src/main.ts",
post: "src/cleanup.ts",
},
build: {
minify: true,
sourceMap: false,
},
});
`
Your action.yml must use Node.js 24:
`yaml`
name: "My Action"
description: "Does something useful"
runs:
using: "node24"
main: "dist/main.js"
post: "dist/post.js" # Optional
- Getting Started - Installation and first build
- Configuration - All configuration options
- CLI Reference - Complete command reference
- Architecture - How it works internally
- Troubleshooting - Common issues and solutions
Use the builder programmatically in your scripts:
`typescript
import { GitHubAction } from "@savvy-web/github-action-builder";
const action = GitHubAction.create();
const result = await action.build();
if (result.success) {
console.log(Built ${result.build?.entries.length} entry points);`
}
- Node.js 24+
- TypeScript source files
- action.yml with runs.using: "node24"`
MIT