GitHub Actions - Workflows as Code (WAC)

Overview

github-actions-wac

license code style: prettier PRs Welcome

GitHub Actions - Workflows as Code (WaC).

Table of Contents

Installation

npm install --save github-actions-wac --dev

Or if you prefer yarn:

yarn add github-actions-wac --dev

Overview

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:

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

Why Create GitHub Actions via Code?

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)

Examples

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.

Reference

Functions

createWorkflow

Type Declaration

export declare const createWorkflow: (workflow: Workflow) => Workflow;

Creates a new GitHub Actions workflow. Accepts a Workflow object.

import { createWorkflow } from "github-actions-wac";

export const push = createWorkflow({
    name: "Push to main branch",
    on: "push",
    env: defaultEnv,
    jobs: { ... }
});

CLI

This package includes a small CLI that can be invoked via npx or yarn:

# Using npx:
npx github-actions-wac

# Using yarn: 
yarn 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.

build

Builds YAML from detected TypeScript (.wac.ts) workflow files.

npx github-actions-wac build

watch

Watches for changes in detected TypeScript (.wac.ts) workflow files and automatically generates YAML.

npx github-actions-wac watch
You might also like...

Windmill: Open-source platform and runtime to turn any scripts into internal apps, integrations and workflows

Windmill: Open-source platform and runtime to turn any scripts into internal apps, integrations and workflows

. Open-source and self-hostable alternative to Airplane, Pipedream, Superblocks and a simplified Temporal with autogenerated UIs to trigger flows and

Jan 4, 2023

Workflows für REDAXO 5 Addons

Github-Workflows für REDAXO 5 Addons In diesem Repository findet ihr Workflows für eure REDAXO-Addons. Diese sollen euch als Hilfe für den Einstieg di

Nov 30, 2022

Track Apple software update changes with Github Actions

What is this? This repo is scraping known Apple software update URLs and keeps the results in recursively sorted (and therefore diffable) JSON files.

Dec 8, 2022

Sample of CI/CD auto deploy to own server via Github Actions

Psst — looking for a more complete solution? Check out SvelteKit, the official framework for building web applications of all sizes, with a beautiful

Mar 19, 2022

Assume AWS IAM Roles using SAML.to in GitHub Actions

assume-aws-role-action This action enables workflows to obtain AWS Access Credentials for a desired IAM Role using AWS IAM SAML and a GitHub Actions R

Dec 31, 2022

GitHub Actions Tutorial

GitHub Actions Tutorial This is a brief intro of how to use GitHub Actions for a frontend (static S3) and a backend (lambda). If you want to learn mor

Mar 4, 2022

Fullstack Turborepo starter. Typescript, Nestjs, Nextjs, Tailwind, Prisma, Github Actions, Docker, And Reverse proxy configured

Turborepo (NestJS + Prisma + NextJS + Tailwind + Typescript + Jest) Starter This is fullstack turborepo starter. It comes with the following features.

Jan 9, 2023

Github Actions for Bizfly Cloud - bizflyctl

GitHub Actions for BizflyCloud This action enables you to interact with Bizfly Cloud services by installing the bizflyctl command-line client Usage To

Mar 17, 2022

A GitHub app to report failed workflow job actions and notify pull request creator with custom report message for the failed workflow job.

A GitHub app to report failed workflow job actions and notify pull request creator with custom report message for the failed workflow job.

Workflow Reporter A GitHub App built with Probot that reports failed workflow job actions and notify the pull request creator with custom report messa

Nov 12, 2022
Comments
  • The automated release is failing 🚨

    The automated release is failing 🚨

    :rotating_light: The automated release from the main branch failed. :rotating_light:

    I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

    You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

    Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

    Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the main branch. You can also manually restart the failed CI job that runs semantic-release.

    If you are not sure how to resolve this, here are some links that can help you:

    If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.


    Missing package.json file.

    A package.json file at the root of your project is required to release on npm.

    Please follow the npm guideline to create a valid package.json file.


    Good luck with your project ✨

    Your semantic-release bot :package::rocket:

    semantic-release 
    opened by github-actions[bot] 0
  • The automated release is failing 🚨

    The automated release is failing 🚨

    :rotating_light: The automated release from the main branch failed. :rotating_light:

    I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

    You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

    Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

    Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the main branch. You can also manually restart the failed CI job that runs semantic-release.

    If you are not sure how to resolve this, here are some links that can help you:

    If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.


    Missing package.json file.

    A package.json file at the root of your project is required to release on npm.

    Please follow the npm guideline to create a valid package.json file.


    Good luck with your project ✨

    Your semantic-release bot :package::rocket:

    semantic-release 
    opened by github-actions[bot] 0
  • Disable YAML references

    Disable YAML references

    When reusing chunks (as JS objects), YAML package will define repeated objects as a YAML reference.

    I think that is ok, since they are meant to be machine readable. But I still think it diminishes DX, as the final workflows are not easily readable by a human (for verification purposes).

    I defined a step as a JS object, and then included it twice into steps array:

    image

    opened by moltar 2
  • Export composable types

    Export composable types

    First of all, a really nice package! Thanks for that. 🙌🏼


    Now, to the actual issue...

    Since the entire point of defining "as code" is to be able to reuse chunks of definitions. I feel like then types need to be exported for each chunk that can be reused.

    For example, there is no exported type for a step, and even trying to do various TypeScript acrobatics to infer the type, it won't work, since the step type is a complicated union.

    I think each composable type needs to be exported.

    At least:

    • Step
    • Job
    • Workflow

    Or factory functions, like createWorkflow.

    At the same time, there are many types that are exported, which are not needed.

    image

    opened by moltar 1
Releases(v1.3.0)
Owner
Webiny
Open-source platform for building serverless applications and APIs.
Webiny
Create deployment files and configure GitHub Actions workflows to deploy applications to Azure Kubernetes Service (AKS).

Azure Kubernetes Service (AKS) DevX (Developer experience) Extension for Visual Studio Code (Preview) The AKS DevX extension for Visual Studio Code (P

Microsoft Azure 11 Oct 1, 2022
Github Actions and Workflows that make maintaining Magento2 projects and modules easier.

Magento 2 GitHub Actions Opinionated Github Actions and Workflows to make building, testing, and maintaining Magento 2 Modules easier. README if you a

Graycore, LLC 35 Dec 21, 2022
A GitHub Action that allows to debug GitHub workflows using VS Code.

VS Code Server Action A GitHub Action that allows to debug GitHub workflows using VS Code. Failing CI builds can be annoying especially since we don't

stateful 18 Dec 23, 2022
Deploy an Architect project from GitHub Actions with keys gathered from aws-actions/configure-aws-credentials

Deploy an Architect project from GitHub Actions with keys gathered from a specific AWS IAM Role federated by an IAM OIDCProvider. CloudFormation to cr

Taylor Beseda 4 Apr 6, 2022
Github action to collect metrics (CPU, memory, I/O, etc ...) from your workflows to help you debug and optimize your CI/CD pipeline

workflow-telemetry-action A GitHub Action to track and monitor the resource metrics of your GitHub Action workflow runs. If the run is triggered via a

Thundra 32 Dec 30, 2022
Manage GitHub resources like repositories, teams, members, integrations and workflows with the AWS CDK as Custom Resources in CloudFormation.

CDK Github Manage GitHub resources like repositories, teams, members, integrations and workflows with the AWS CDK as Custom Resources in CloudFormatio

Pepperize 8 Nov 25, 2022
Create a badge using GitHub Actions and GitHub Workflow CPU time

Generated Badges Create a badge using GitHub Actions and GitHub Workflow CPU time (no 3rd parties servers) Install $ npm i generated-badges -g Command

小弟调调™ 9 Dec 30, 2022
A Docusaurus website deployed to GitHub Pages using GitHub Actions.

Deploy Docusaurus website to GitHub Pages using GitHub Actions This repository is an example of deploying a Docusaurus website to GitHub Pages using G

Lars Gyrup Brink Nielsen 18 Dec 26, 2022
Drag and drop Argo Workflows tool.

Visual Argo Workflows Live demo The goal of this project is to make it easier for everyone on a team to construct and run their own workflows. Workflo

Artem Golub 38 Dec 22, 2022
AWS Step Functions Workflows Collection

AWS Step Functions Workflows Collection This repo contains Step Functions workflows that shows how to orchestrate multiple services into business-crit

AWS Samples 76 Dec 25, 2022