Generaptor 1.0.0

🦖 Generaptor

Generaptor helps you to maintain GitHub actions for your project. It can generate the YAML files, according to the specification defined in your code.

Now you can manage your action definitions via NuGet packages, and port the whole workflows between repositories. A bit of strong typing will also help to avoid mistakes!

Showcase

Consider this F# program (this is actually used in this very repository):

let mainBranch = "main"
let images = [
    "macos-12"
    "ubuntu-22.04"
    "windows-2022"
]

let workflows = [
    workflow "main" [
        name "Main"
        onPushTo mainBranch
        onPullRequestTo mainBranch
        onSchedule(day = DayOfWeek.Saturday)
        onWorkflowDispatch
        job "main" [
            checkout
            yield! dotNetBuildAndTest()
        ] |> addMatrix images
    ]
]

[<EntryPoint>]
let main(args: string[]): int =
    EntryPoint.Process args workflows

(See the actual example with all the imports in the main program file.)

It will generate the following GitHub action configuration:

name: Main
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  schedule:
    - cron: 0 0 * * 6
  workflow_dispatch:
jobs:
  main:
    strategy:
      matrix:
        image:
          - macos-12
          - ubuntu-22.04
          - windows-2022
      fail-fast: false
    runs-on: ${{ matrix.image }}
    env:
      DOTNET_CLI_TELEMETRY_OPTOUT: 1
      DOTNET_NOLOGO: 1
      NUGET_PACKAGES: ${{ github.workspace }}/.github/nuget-packages
    steps:
      - uses: actions/checkout@v4
      - name: Set up .NET SDK
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 8.0.x
      - name: NuGet cache
        uses: actions/cache@v4
        with:
          key: ${{ runner.os }}.nuget.${{ hashFiles('**/*.fsproj') }}
          path: ${{ env.NUGET_PACKAGES }}
      - name: Build
        run: dotnet build
      - name: Test
        run: dotnet test
        timeout-minutes: 10

How to Use

1. Create a new F# project in your solution. The location doesn't matter, but we recommend calling it GitHubActions and put inside the Infrastructure solution folder, to not mix it with the main code.

2. Install the Generaptor.Library NuGet package.

3. Call the Generaptor.EntryPoint.Process method with the arguments passed to the main function and the list of workflows you want to generate.

4. Run the program from the repository root folder in your shell, for example:

   $ cd <your-repository-root-folder>
   $ dotnet run --project ./Infrastructure/GitHubActions
   

   When called with empty arguments of with command generate, it will (re-)generate the workflow files in .github/workflows folder, relatively to the current directory.

For basic GitHub Action support (workflow and step DSL), see the GitHubActions.fs file. The basic actions are in the main Generaptor package.

For advanced patterns and action commands ready for use, see Actions and Patterns files. These are in the auxiliary Generaptor.Library package.

Feel free to create your own actions and patterns, and either send a PR to this repository, or publish your own NuGet packages!

Documentation

• Changelog
• License (MIT)
• Maintainer Guide
• Code of Conduct (adapted from the Contributor Covenant)