Github Actions Typescript

Problem: It's difficult to manage YAML files for Github Actions and easy to make mistakes.

Solution: Create a set of common typings that can be used to programatically construct your Github Actions workflows.

This package provides a set of classes and utilities to programmatically generate GitHub Actions workflows, jobs, and steps in TypeScript. It offers a structured way to define complex workflows, ensuring that all configurations are validated and correctly formatted before being written to YAML files.

Features

• Workflow Class: Defines the overall workflow configuration, including triggers (on), environment variables, job definitions, concurrency settings, and more.
• Job Class: Represents individual jobs within a workflow, including their execution environment, dependencies, permissions, and steps.
• Step Classes: Provides RunStep and UsesStep classes to define the individual steps within a job. RunStep allows you to execute commands, while UsesStep lets you leverage pre-built GitHub Actions.

Installation

npm install github-actions-typescript

Usage

Creating a Workflow

import { Workflow } from "./workflow";
import { Job } from "./job";
import { RunStep, UsesStep } from "./step";

// Define a new workflow
const workflow = new Workflow("example.yml", {
  name: "CI/CD Pipeline",
  on: ["push", "pull_request"],
  env: {
    NODE_ENV: "production",
  },
});

// Define a job
const job = new Job({
  name: "Build and Test",
  "runs-on": "ubuntu-latest",
  steps: [
    new RunStep({
      name: "Checkout code",
      run: "git checkout ${{ github.ref }}",
    }),
    new RunStep({
      name: "Install dependencies",
      run: "npm install",
    }),
    new RunStep({
      name: "Run tests",
      run: "npm test",
    }),
  ],
});

// Add job to workflow
workflow.addJob({ id: "build-and-test", job });

// Write the workflow to a file
await workflow.writeToFile();

Structure

• Workflow: Represents the entire workflow configuration. It includes:

  • filename: The name of the YAML file to generate.
  • on: The events that trigger the workflow.
  • env: Environment variables available to all jobs.
  • jobs: The list of jobs that will run as part of this workflow.

• Job: Represents a job within a workflow. It includes:

  • name: The job's name.
  • runs-on: The environment where the job will execute.
  • steps: A list of steps to execute as part of the job.

• RunStep: Represents a shell command to run within a job.

  • run: The command to execute.
  • shell: The shell to use for executing the command.

• UsesStep: Represents an action to use within a job.

  • uses: The GitHub Action to use.

Example Workflow Output

The example above generates a YAML file like this:

# This file is autogenerated. Do not modify manually.

name: CI/CD Pipeline
on:
  - push
  - pull_request
env:
  NODE_ENV: production

jobs:
  build-and-test:
    name: Build and Test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        run: git checkout ${{ github.ref }}
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

Validation

The package includes validation methods to ensure that your workflow configuration is correct. For example:

• Ensures that the on property is properly defined.
• Validates the shell types in RunStep.
• Ensures required properties are set, such as runs-on in jobs and run in RunStep.

Contributing

Feel free to open issues or submit pull requests. Contributions are welcome!

License

This project is licensed under the MIT License. See the LICENSE file for details.