@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:

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

Usage

$3

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

`ts
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)
`

$3

`bash
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.

$3

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

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

export default config
`

$3

`json
{
"refs": false,
"headerText": [
"# Auto-generated from ",
"# 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 as placeholder. | Default header |
| dumpOptions | Options for js-yaml dump function | Default options |

Integration with Husky

For seamless automation, integrate with husky:

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

Add to package.json:
`json
{
"scripts": {
"build:workflows": "npx gwf build && git add .github/workflows/*.yml"
}
}
`

Add pre-commit hook:
`bash
npx husky add .husky/pre-commit "npm run build:workflows"
``

Documentation

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

License

MIT