@github-actions-workflow-ts/cli

CLI to generate GitHub Actions YAML workflow files from TypeScript.

Stop writing workflows in YAML and use TypeScript instead!

Installation

Install both the library and CLI:

npm install --save-dev @github-actions-workflow-ts/lib @github-actions-workflow-ts/cli

Usage

1. Write your workflow in TypeScript

Create a *.wac.ts file (e.g., deploy.wac.ts) anywhere in your project:

import { Workflow, NormalJob, Step } from '@github-actions-workflow-ts/lib'

const checkoutStep = new Step({
  name: 'Checkout',
  uses: 'actions/checkout@v3',
})

const testJob = new NormalJob('Test', {
  'runs-on': 'ubuntu-latest',
  'timeout-minutes': 2
})

// IMPORTANT: Export the workflow to generate the YAML file
export const exampleWorkflow = new Workflow('example-filename', {
  name: 'Example',
  on: {
    workflow_dispatch: {}
  }
})

testJob.addStep(checkoutStep)
exampleWorkflow.addJob(testJob)

2. Generate the YAML files

npx gwf build

# OR

npx generate-workflow-files build

This will generate .github/workflows/example-filename.yml from your TypeScript workflow definition.

CLI Commands

| Command | Alias | Description | |---------|-------|-------------| | gwf build | generate-workflow-files build, gawts build | Generate YAML workflow files from *.wac.ts files |

Configuration

Create a config file in your project root to customize generation. Both TypeScript (wac.config.ts) and JSON (wac.config.json) formats are supported. TypeScript config takes precedence if both exist.

TypeScript Config (Recommended)

// wac.config.ts
import type { WacConfig } from '@github-actions-workflow-ts/cli'

const config: WacConfig = {
  refs: false,
  headerText: [
    '# Auto-generated from <source-file-path>',
    '# Do not edit this file directly',
  ],
}

export default config

JSON Config

{
  "refs": false,
  "headerText": [
    "# Auto-generated from <source-file-path>",
    "# Do not edit this file directly"
  ]
}

| Property | Description | Default | |----------|-------------|---------| | refs | Convert duplicate objects into YAML references | false | | headerText | Custom header text for generated files. Use <source-file-path> as placeholder. | Default header | | dumpOptions | Options for js-yaml dump function | Default options |

Integration with Husky

For seamless automation, integrate with husky:

npm install --save-dev husky
npx husky-init

Add to package.json:

{
  "scripts": {
    "build:workflows": "npx gwf build && git add .github/workflows/*.yml"
  }
}

Add pre-commit hook:

npx husky add .husky/pre-commit "npm run build:workflows"

Documentation

For full documentation, examples, and API reference, visit the main repository.

License

MIT