@savvy-web/github-action-builder

@savvy-web/github-action-builder

A 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.

Features

• 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

Quick Start

Create a new GitHub Action project with a single command:

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:

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. Your bundled action is in dist/main.js, ready to commit and use.

Basic Usage

Initialize

Create a new GitHub Action project:

npx @savvy-web/github-action-builder init my-action

Build

Bundle all entry points into dist/:

npm run build
# or directly:
npx @savvy-web/github-action-builder build

Validate

Check your action.yml and configuration without building:

npm run validate
# or directly:
npx @savvy-web/github-action-builder validate

Project Structure

The builder expects this structure:

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

Configuration

Customize action.config.ts for your project:

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,
  },
});

action.yml Requirements

Your action.yml must use Node.js 24:

name: "My Action"
description: "Does something useful"
runs:
  using: "node24"
  main: "dist/main.js"
  post: "dist/post.js" # Optional

Documentation

• 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

Programmatic API

Use the builder programmatically in your scripts:

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`);
}

Requirements

• Node.js 24+
• TypeScript source files
• action.yml with runs.using: "node24"

License

MIT