elegantchaos/actionbuildercore

Requirements

• Swift 6.2 toolchain (for building this package)
• macOS 26 or later

Usage

This package defines a library (ActionBuilderCore), and a command line tool (ActionBuilderTool).

To use the tool to generate a workflow for your package, you can run the following command from the root of this repository:

swift run ActionBuilderTool <path-to-your-package>

If you want to install the tool globally, the easiest way is probably with Mint:

mint install elegantchaos/ActionBuilderCore

(If you need to install Mint first, easiest way is probably with Homebrew: brew install mint)

Assuming that you've added Mint's bin folder to your path, you can then just do:

ActionBuilderTool <path-to-your-package>

The package path is optional when running like this -- if you omit it, the tool assumes that you want to generate a workflow for the package in the current directory.

Options

You can pass a few options to ActionBuilderTool:

• --create-config: This will make a new empty .actionbuilder.json file in the package directory.
• --edit-config: This will open the package's .actionbuilder.json file for editing.
• --reveal-config: This will reveal the package's .actionbuilder.json file in the Finder.

Configuration

The exact steps that the workflow executes can be configured.

These include:

• platforms to test, from: macOS, iOS, tvOS, watchOS, linux
• swift versions to test against: 5.10, 6.0, 6.1, 6.2 and the main snapshot.
• the configuration to test: debug, release
• whether to run tests or just build
• whether to upload build logs
• whether to post a notification to a slack channel
• whether to amend a header to the README
• whether to test against every requested swift version, or just the earliest and latest

These settings are read from an .actionbuilder.json file in the root of the package directory. If it is missing, some defaults are chosen.

If they aren't explicitly set in the configuration file, the code attempts to pick sensible values by examining the Package.swift manifest:

• the tool version of the manifest is used to determine the version of Swift to test against.
• the platform minimum deployment versions listed in the manifest are used to determine platforms to test against

If the package manifest includes a minimum deployment for .custom("Ubuntu", ...), the linux platform is added. The version number specified in this minimum deployment is currently ignored, but may eventually be used to determine the version of the runner image to use for the runs-on: ubuntu- entry of the workflow job.

If no minimum deployment information is present, the macOS and linux platforms are added by default. If these defaults aren't what you need, you can specify exact values using a config file (see below).

Config Format

In an ideal world I'd like all of the configuration information that the tool requires to be extracted from the Package.swift file.

However, there are some situations where you may want to customise the behaviour slightly.

In this case you can add a .actionbuilder.json file at the root of the project.

Here is an example:

{
    "name": "TestPackage",
    "owner": "TestOwner",
    "platforms": ["macOS", "linux"],
    "compilers": ["swift510", "swiftNightly"],
    "configurations": ["release"],
    "test": true,
    "header": false,
    "firstlast": false,
    "uploadLogs": false,
    "postSlackNotification": false
}

History

This code was originally part of Action Status, which is a little macOS/iOS tool I made for monitoring Github Actions.

I've now split the code out so that it can be used in other places.

I plan to remove the generation functionality from Action Status, and instead make a standalone Action Builder application (probably macOS only).

I have also created an SPM command plugin, so that you can generate workflows directly from the command line.

Package Metadata

Repository: elegantchaos/actionbuildercore

Default branch: main

README: README.md