Generaptor.Library 1.12.0

🦖 Generaptor 👁 Status Ventis

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!

NuGet package links:

• 👁 Generaptor
  
• 👁 Generaptor.Library
  

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

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

Quick Start

If you want to start using Generaptor in a project with pre-existing CI pipeline, follow these steps.

1. Create a new file scripts/github-actions.fsx (or at any other directory of your preference).
2. Write the following code in it:

   #r "nuget: Generaptor, 1.12.0"
   open Generaptor
   exit <| EntryPoint.Process fsi.CommandLineArgs []
   

3. Run dotnet fsi scripts/github-actions.fsx regenerate scripts/github-actions.fsx — this will read your CI definitions from ./github/workflows and fill the script file with the instructions to regenerate them.

After that, modify the script and see how it updates the CI pipeline definition in the .github folder. See the instructions below.

Reference

We recommend two main modes of execution for Generaptor: from a .NET project and from a script file.

.NET Project

This integration is useful if you already have a solution file, and it's more convenient for you to have your infrastructure in a new project in that solution. Follow this instruction.

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
   

   See the Command-Line Arguments section for more details.

Script File

As an alternative execution mode, we also support execution from an F# script file.

Put your code (see an example below) into an .fsx file (say, github-actions.fsx), and run it with the following shell command:

$ dotnet fsi github-actions.fsx [optional parameters may go here]

The script file example:

#r "nuget: Generaptor.Library, 1.12.0"
open System

open Generaptor
open Generaptor.GitHubActions
open type Generaptor.GitHubActions.Commands
open type Generaptor.Library.Actions
open type Generaptor.Library.Patterns

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
 ]
]

exit <| EntryPoint.Process fsi.CommandLineArgs workflows

Command-Line Arguments

Generaptor supports the following command-line arguments:

• no arguments or generate — (re-)generate the workflow files in the .github/workflows folder, relatively to the current directory;
• verify — read the current workflows form .github/workflows and compare them with the script contents. If any are different, print diagnostic message and exit with non-zero exit code.
• regenerate [path to fsx file] — generate the .fsx script file from the .yml workflows in the repository (the .github/workflows folder, relative to the current directory).

Automatic Version Extraction

For cases when you manage your action versions separately (using tools like Dependabot or Renovate), you can set up Generaptor to read the action versions from your YAML definitions. This way, it will read the versions, then regenerate the file, and apply the versions read previously — thus preserving the flow you have with external tools.

To use it, define steps using the Auto notation:

let workflows = [
 workflow "main" [
 job "main" [
 // Obsolete way, will not auto-update:
 // step(uses = "actions/checkout@v4")
 // New way, will work well with external update:
 step(usesSpec = Auto "actions/checkout")
 ]
 ]
]

Auto notation will try to guess the latest used major action version from the corresponding .yml file; failing that, will find the latest used minor version, and failing that — will fetch the latest version from the corresponding action's repository.

It supports version tags in form of [v]X[.Y[.Z]], where X, Y, and Z are numbers.

Library Features

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

For advanced patterns and action commands ready for use, see and 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!

GitHub Actions Usage

Example usage to set up script verification on CI:

job "verify-workflows" [
 runsOn "ubuntu-latest"

 setEnv "DOTNET_CLI_TELEMETRY_OPTOUT" "1"
 setEnv "DOTNET_NOLOGO" "1"
 setEnv "NUGET_PACKAGES" "${{ github.workspace }}/.github/nuget-packages"
 step(
 usesSpec = Auto "actions/checkout"
 )
 step(
 usesSpec = Auto "actions/setup-dotnet"
 )
 step(
 run = "dotnet fsi ./scripts/github-actions.fsx verify"
 )
]

Renovate

If you use Renovate, set up the auto-update with this snippet in renovate.json:

{
 "$schema": "https://docs.renovatebot.com/renovate-schema.json",
 "extends": [
 "config:recommended"
 ],
 "customManagers": [
 {
 "description": "Update the Generaptor package.",
 "customType": "regex",
 "managerFilePatterns": [
 "scripts/github-actions.fsx"
 ],
 "matchStrings": [
 "#r \"nuget: (?<depName>.+), (?<currentValue>\\S+)\""
 ],
 "datasourceTemplate": "nuget"
 }
 ]
}

Versioning Notes

This project's versioning follows the Semantic Versioning 2.0.0 specification.

When considering compatible changes, we currently only consider the source compatibility with the user scripts, not binary compatibility. This may be subject to change in the future.

Documentation

License

The project is distributed under the terms of .

The license indication in the project's sources is compliant with the [REUSE specification v3.3][reuse.spec].