GitHub Actions Workflows

This repository will contain reusable workflows to minimize redundant workflows across the organization. This effort will also facilitate the standardization of testing processes while empowering repository code owners to customize their testing plans as needed. The repository will contain workflows to support different types of repositories, such as Swift Package and Swift Compiler.

For more details on reusable workflows, please refer to the Reusing workflows section in the GitHub Docs.

Reusable workflow for Swift package repositories

There are different kinds of workflows that this repository offers:

Soundness

The soundness workflows provides a multitude of checks to ensure a repository is following the best practices. By default each check is enabled but can be disabled by passing the appropriate workflow input. We recommend to adopt all soundness checks and enforce them on each PR.

A recommended workflow looks like this:

name: Pull request

on:
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  soundness:
    name: Soundness
    uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.1
    with:
      license_header_check_project_name: "Swift.org"

Testing

To enable pull request testing for all supported Swift versions (5.9, 5.10, 6.0, 6.1, 6.2, nightly, and nightly-6.3) on Linux and Windows, add the following code example in .github/workflows/pull_request.yml:

name: pull_request

on:
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  tests:
    name: tests
    uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@0.0.1

If your package only supports newer compiler versions, you can exclude older versions by using the *_exclude_swift_versions workflow input:

linux_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}]"
windows_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}]"

Additionally, if your package requires additional installed packages, you can use the pre_build_command. For example, to install a package called example:

pre_build_command: "which example || (apt update -q && apt install -yq example"

macOS platform support will be available soon.

Cross-PR testing

To support testing of PRs together with PRs for one of the package’s dependencies, set add the following to your PR job.

with:
  enable_cross_pr_testing: true

To reference a linked PR, add Linked PR: <link to PR> to the PR description, eg.

Linked PR: https://github.com/swiftlang/swift-syntax/pull/2859
// or alternatively
Linked PR: swiftlang/swift-syntax#2859

Enabling cross-PR testing will add about 10s to PR testing time.

CMake Build

The cmake_build workflow installs a pinned CMake (using the install-cmake action) and runs your configure and build commands across Linux, macOS, and Windows. It removes the boilerplate of installing CMake and wiring up $CMAKE-based build steps in each consumer.

By default it installs CMake 4.0.3, configures with $CMAKE -G Ninja -B build -S ., and builds with $CMAKE --build build. Linux builds run by default. macOS and Windows builds can be enabled with enable_macos_checks and enable_windows_checks respectively. A minimal example:

name: Pull request

on:
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  cmake_build:
    name: CMake Build
    uses: swiftlang/github-workflows/.github/workflows/cmake_build.yml@<version>

Override the per-platform configure and build commands to point at your project. $CMAKE and $CTEST are exposed as environment variables, and the installed CMake is also on PATH:

with:
  linux_configure_command: "$CMAKE -G Ninja -B build -S Sources -DCMAKE_BUILD_TYPE=Release"
  linux_build_command: "$CMAKE --build build"

The default configure command uses the Ninja generator, but the workflow does not install Ninja. Ensure Ninja is available in your environment, install it via a *_pre_build_command, or override the configure command to use a different generator:

with:
  linux_pre_build_command: "apt-get install -y ninja-build"

To pin a different CMake version, override cmake_version together with the matching per-platform SHA-256 hashes (linux_x86_64_hash, linux_aarch64_hash, macos_hash, windows_x86_64_hash, windows_arm64_hash).

Evolution Proposal Validation

The proposal validation workflow validates added and changed proposals in a pull request to check for formatting and content errors that will cause metadata extraction to fail or be incomplete.

To accomplish this, the workflow builds the swift-evolution-metadata-extractor tool and runs its validate command. To minimize validation times, the built tool is cached and only rebuilt when the tool has changed.

To use the proposal validation workflow, add a workflow to the repository that contains the directory of proposals. The calling workflow specifies project-specific details such as the directory where the proposals are located. It is only run if a pull request contains changes in the specified directory.

Note

The extraction tool currently only supports the evolution proposals of the Swift project at swiftlang/swift-evolution/proposals. The tool and workflow has been designed to be extended to support additional projects in the future.

An example workflow for Swift Testing which uses a subfolder in the swift-evolution repository:

name: Validate proposals with swift-evolution-metadata-extractor

on:
  pull_request:
    types: [opened, reopened, synchronize]
    branches:
      - 'main'
    paths:
      - 'proposals/testing/*'

jobs:
  validate:
    name: Validate Proposals
    uses: swiftlang/github-workflows/.github/workflows/proposal_validation.yml@main
    with:
      project: "testing"

Running workflows locally

You can run the Github Actions workflows locally using act. To run all the jobs that run on a pull request, use the following command:

% act pull_request

To run just a single job, use workflow_call -j <job>, and specify the inputs the job expects. For example, to run just shellcheck:

% act workflow_call -j soundness --input shell_check_enabled=true

To bind-mount the working directory to the container, rather than a copy, use --bind. For example, to run just the formatting, and have the results reflected in your working directory:

% act --bind workflow_call -j soundness --input format_check_enabled=true

If you'd like act to always run with certain flags, these can be be placed in an .actrc file either in the current working directory or your home directory, for example:

--container-architecture=linux/amd64
--remote-name upstream
--action-offline-mode