github-actions-workflow-ts

Write GitHub Actions workflows in TypeScript instead of YAML!

Quick Install

npm install --save-dev \
  @github-actions-workflow-ts/lib \      # types for workflows
  @github-actions-workflow-ts/cli \      # generates the yaml
  @github-actions-workflow-ts/actions    # types for popular gha actions

Quick Example

// workflows/ci.wac.ts
import { 
  Workflow, 
  NormalJob, 
  Step, 
  expressions as ex, 
  dedentString as ds 
} from '@github-actions-workflow-ts/lib'
import { 
  ActionsCheckoutV4, 
  ActionsSetupNodeV4
} from '@github-actions-workflow-ts/actions'

const checkout = new ActionsCheckoutV4({
  name: 'Checkout',
})

const setupNode = new ActionsSetupNodeV4({
  id: 'setup-node',
  name: 'Setup Node.js',
  // Typed actions give you autocomplete on `with` inputs and typed `outputs`
  with: {
    'node-version': '20.x',
    cache: 'npm',
  },
})

// Plain steps work too — use whichever style fits
const script = new Step({
  name: 'Simple script',
  run: ds(`
    for i in {1..5}; do
      if [ $i -eq 3 ]; then
        echo "This is number three!"
      else
        echo "Number: $i"
      fi
    done
  `)
})

const test = new Step({
  name: 'Run tests',
  run: 'npm test',
  env: {
    CI: 'true',
    // you can use expression helpers -> ${{ secrets.NPM_TOKEN }}
    NODE_AUTH_TOKEN: ex.secret('NPM_TOKEN'),
  },
})


const testJob = new NormalJob('test', {
  'runs-on': 'ubuntu-latest',
}).addSteps([checkout, setupNode, script, test])

// Every Workflow instance MUST be exported
export const ci = new Workflow('ci', {
  name: 'CI',
  on: {
    push: { branches: ['main'] },
    pull_request: { branches: ['main'] },
  },
}).addJobs([testJob])

Generate the YAML:

# creates .github/workflows/ci.yml
npx gwf build

See more examples in the ./examples folder and their respective output in ./.github/workflows.

Documentation

View Full Documentation

• Installation
• Quick Start
• Writing Workflows
• Helpers
• Typed Actions
• API Reference

Packages

Package	Description
@github-actions-workflow-ts/lib	Core lib for generating workflow JSON objects
@github-actions-workflow-ts/cli	CLI for generating YAML files
@github-actions-workflow-ts/actions	Typed wrappers for popular actions

Try It Out

Explore on CodeSandbox:

• Simple Example
• Advanced Example

Contributing

See the Contributing Guide

License

MIT