GitHub Actions - Workflows as Code (WaC).
npm install github-actions-wacgithub-actions-wac






GitHub Actions - Workflows as Code (WaC).
- Installation
- Overview
- Examples
- Reference
- Functions
- createWorkflow
- CLI
- build
- watch
```
npm install --save github-actions-wac --dev
Or if you prefer yarn:
``
yarn add github-actions-wac --dev
The github-actions-wac package enables you to create GitHub Actions workflows via TypeScript code.
To get started, simply create a new .wac.ts file in your .github/workflows folder and start creating your GitHub Actions workflow. For example:
`ts
// .github/workflows/index.wac.ts
import { createWorkflow, NormalJob } from "github-actions-wac";
// Some global environment variables.
const defaultEnv = {
NODE_OPTIONS: "--max_old_space_size=4096"
};
// Let's assign some of the common steps into a standalone const.
const checkoutInstallBuildTest: NormalJob["steps"] = [
{ uses: "actions/checkout@v2" },
{ name: "Install dependencies", run: "yarn --immutable" },
{ name: "Build", run: "yarn build" }
];
// Create "Push to main branch" workflow.
export const push = createWorkflow({
name: "Push to main branch",
on: "push",
env: defaultEnv,
jobs: {
buildTestRelease: {
name: "Build, test, release",
"runs-on": "ubuntu-latest",
steps: [
...checkoutInstallBuildTest,
{
name: "Release",
uses: "cycjimmy/semantic-release-action@v3",
with: { working_directory: "./dist" },
env: {
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}",
NPM_TOKEN: "${{ secrets.NPM_TOKEN }}"
}
}
]
}
}
});
// Create "Pull requests" workflow.
export const pullRequests = createWorkflow({
name: "Pull requests",
on: "pull_request",
env: defaultEnv,
jobs: {
buildTest: {
name: "Build and test",
"runs-on": "ubuntu-latest",
steps: [...checkoutInstallBuildTest]
}
}
});
`
Once you're done, in your terminal, simply run the npx github-actions-wac build (or npx ghawac build) CLI command to emit regular YAML files. For example, if we were to build the above example, we'd end up with two YAML files: push.yml and pullRequests.yml.
> The npx github-actions-wac build commands detects all exported workflows from .wac.ts files and emits a standalone YAML file for each one.
> It's up to you to decide whether you want a single .wac.ts file that exports all workflows, or multiple .wac.ts files where each exports a single workflow.
Creating GitHub Actions workflows via (TypeScript) code has a couple of benefits:
- if you don't like YAML in general, then this might be a more favorable approach
- type safety - the mentioned npx github-actions-wac build CLI command will throw TypeScript errors if something is wrong
- no need to copy/paste dozens of lines of YAML - simply store all of your repetitive jobs/steps as variables (or even as factory functions if additional dynamicity is required)
- it's even possible to import external NPM modules if needed (although, personally I haven't had the need to do it yet)
| Example | Description |
| ------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Simple Workflow | Exports a single workflow that consists of a couple of a single job and some steps. |
| Multiple Workflows | Exports multiple workflows that consist of a single jobs and multiple steps. |
| Complex Example | A more complex example that exports multiple branch-dependent workflows. |
#### createWorkflow
`Type Declaration
ts`
export declare const createWorkflow: (workflow: Workflow) => Workflow;
Creates a new GitHub Actions workflow. Accepts a Workflow object.
`ts
import { createWorkflow } from "github-actions-wac";
export const push = createWorkflow({
name: "Push to main branch",
on: "push",
env: defaultEnv,
jobs: { ... }
});
`
This package includes a small CLI that can be invoked via npx or yarn:
`bashUsing npx:
npx github-actions-wac
> Instead of
github-actions-wac, you can also use ghawac to invoke the CLI. For example: npx ghawac (yarn ghawac).> You can also run
npx github-actions-wac --help for in-terminal reference.####
buildBuilds YAML from detected TypeScript (
.wac.ts) workflow files.`bash
npx github-actions-wac build
`####
watchWatches for changes in detected TypeScript (
.wac.ts) workflow files and automatically generates YAML.`bash
npx github-actions-wac watch
``