GitHub Actions Workflows

This repository contains reusable GitHub Actions workflows and a collection of Bash scripts designed to streamline quality checks, documentation, formatting, and maintenance tasks in Swift projects.

The workflows build on the official swiftlang/github-workflows and extend them with additional soundness, documentation, and tooling checks.

These workflows and scripts are designed to be used within GitHub Actions. A basic working knowledge of GitHub Actions is required to configure workflows, understand job execution, and troubleshoot CI failures.

If you are not familiar with GitHub Actions, refer to the official documentation before using or customizing these workflows: GitHub Actions documentation

Install

No installation required.

All scripts are executed directly via curl | bash or through the provided Makefile.

Workflows

This section details the reusable workflows provided by the repository.

1. Extra Soundness Workflow (extra_soundness.yml)

This workflow provides configurable, robust checks and testing:

• Optional Local Swift Dependency Checks: Checks for accidental .package(path:) usage.
• Optional Swift Headers Check: Validates Swift source file headers using a strict 5-line format and respects .swiftheaderignore.
• Optional DocC Warnings Check: Runs DocC analysis with --warnings-as-errors and fails on warnings.
• Optional Swift Test Execution: Runs tests using .build caching for efficiency.
• Multi-Version Support: Tests across multiple Swift versions, configurable via input (defaulting to ["6.0", "6.1"]).
• SSH Support: Includes steps to set up SSH credentials (via the SSH_PRIVATE_KEY secret) for projects relying on private Git dependencies.

Workflow Inputs

Input	Description	Default
local_swift_dependencies_check_enabled	Enables local Swift dependency check	false
headers_check_enabled	Enables Swift headers validation	false
docc_warnings_check_enabled	Enables DocC warnings check	false
run_tests_with_cache_enabled	Enables Swift tests with .build cache	false
run_tests_swift_versions	Swift versions to test	["6.1","6.2"]

Example Usage (Caller Repository)

jobs:
  soundness:
    uses: BinaryBirds/github-workflows/.github/workflows/extra_soundness.yml@main
    with:
      local_swift_dependencies_check_enabled: true
      headers_check_enabled: true
      docc_warnings_check_enabled: true
      run_tests_with_cache_enabled: true
      run_tests_swift_versions: '["6.1","6.2"]'

2. DocC Deploy Workflow (docc_deploy.yml)

This workflow handles the generation and deployment of DocC documentation:

• Builds DocC Documentation: Uses a Swift 6.2 Docker image to build the documentation.
• Deploys to GitHub Pages: Uses actions/deploy-pages@v4 to publish the results.
• Target Configuration: Respects .docctargetlist if present.

Example Usage (Caller Repository):

jobs:
  create-docc-and-deploy:
    uses: BinaryBirds/github-workflows/.github/workflows/docc_deploy.yml@main
    permissions:
      contents: read
      pages: write
      id-token: write

---

Makefile Usage

A Makefile is included to simplify the execution of all automation tasks by converting long curl | bash commands into short, memorable make targets.

Combined Makefile Commands

Some Makefile targets group multiple related checks into a single command. These combined commands run several scripts in sequence to provide a quick, consistent way to verify overall project quality. For a concrete reference, see the make check target in the Makefile, which combines several core checks into one command.

Benefits

• Standardizes script usage and ensures consistent options.
• Shortens long commands into memorable tasks.
• Supports composite commands and reduces human error.

---

Available Scripts Documentation

The Makefile uses the variable baseUrl which points to the source of all scripts: https://raw.githubusercontent.com/BinaryBirds/github-workflows/refs/heads/main/scripts

check-api-breakage.sh

Purpose

Detects source- and binary-level API breaking changes in Swift packages to prevent unintended public API regressions.

Behavior

• Uses swift package diagnose-api-breaking-changes
• Pull requests: compares against the PR base branch
• Other contexts: compares against the latest Git tag
• If no tags exist, exits successfully with a warning
• Fails when breaking changes are detected

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/check-api-breakage.sh | bash

---

check-broken-symlinks.sh

Purpose

Ensures all git-tracked symbolic links resolve to valid targets.

Behavior

• Inspects only symbolic links
• Ignores regular missing files
• Reports each broken symlink explicitly
• Exits non-zero if any broken symlink is found

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/check-broken-symlinks.sh | bash

---

check-docc-warnings.sh

Purpose

Runs DocC documentation analysis in strict mode, treating warnings as errors.

Behavior

• Uses .docctargetlist when present, otherwise auto-detects targets
• Temporarily injects swift-docc-plugin if missing
• Requires a clean git working tree locally
• Restores git state after execution

Parameters

None

Ignore files

• .docctargetlist – explicitly defines documented targets

Raw curl example

curl -s $(baseUrl)/check-docc-warnings.sh | bash

---

check-local-swift-dependencies.sh

Purpose

Prevents accidental usage of local Swift package dependencies.

Behavior

• Scans all tracked Package.swift files
• Detects .package(path:)
• Fails immediately on detection

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/check-local-swift-dependencies.sh | bash

---

check-openapi-security.sh

Purpose

Runs a security scan of an OpenAPI specification using OWASP ZAP.

Behavior

• Executes inside Docker
• Skips execution if openapi/ directory does not exist

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/check-openapi-security.sh | bash

---

check-openapi-validation.sh

Purpose

Validates an OpenAPI specification for schema correctness.

Behavior

• Runs the OpenAPI validator in Docker
• Skips execution if openapi/ directory does not exist

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/check-openapi-validation.sh | bash

---

check-swift-headers.sh

Purpose

Ensures Swift source files contain a consistent, standardized header.

Behavior

• Enforces a strict 5-line header format
• Can optionally insert or update headers in-place
• Processes only git-tracked Swift files

Parameters

• --fix – insert or update headers automatically
• --author <name> – override default author name

Ignore files

• .swiftheaderignore – excludes paths from header validation

Raw curl examples

Check only:

curl -s $(baseUrl)/check-swift-headers.sh | bash

Fix headers with custom author:

curl -s $(baseUrl)/check-swift-headers.sh | bash -s -- --fix --author "John Doe"

---

check-unacceptable-language.sh

Purpose

Detects discouraged or outdated terminology to promote inclusive language.

Behavior

• Case-insensitive, whole-word matching
• Scans git-tracked files only

Parameters

None

Ignore files

• .unacceptablelanguageignore – excludes paths from scanning

Raw curl example

curl -s $(baseUrl)/check-unacceptable-language.sh | bash

---

generate-contributors-list.sh

Purpose

Generates a CONTRIBUTORS.txt file from git commit history.

Behavior

• Uses git shortlog
• Respects .mailmap
• Overwrites the file deterministically

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/generate-contributors-list.sh | bash

---

generate-docc.sh

Purpose

Generates DocC documentation into the docs/ directory.

Behavior

• Supports multiple Swift targets
• Enables combined documentation automatically
• Can transform output for static hosting

Parameters

• --local – disable static hosting transform
• --name <value> – set hosting base path

Ignore files

• .docctargetlist – explicitly defines documented targets

Raw curl examples

GitHub Pages output:

curl -s $(baseUrl)/generate-docc.sh | bash -s -- --name MyRepo

Local preview:

curl -s $(baseUrl)/generate-docc.sh | bash -s -- --local

---

install-swift-format.sh

Purpose

Installs the swift-format binary.

Behavior

• Builds from source
• Installs into /usr/local/bin

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/install-swift-format.sh | bash

---

install-swift-openapi-generator.sh

Purpose

Installs the Swift OpenAPI Generator CLI tool.

Behavior

• Builds from source
• Supports version pinning

Parameters

• -v <version> – install a specific version

Ignore files

None

Raw curl examples

Latest version:

curl -s $(baseUrl)/install-swift-openapi-generator.sh | bash

Specific version:

curl -s $(baseUrl)/install-swift-openapi-generator.sh | bash -s -- -v 1.2.2

---

run-clean.sh

Purpose

Removes generated build artifacts and temporary files. ⚠️ Irreversible operation.

Behavior

• Deletes .build, .swiftpm, and generated files
• Intended for local development use

Parameters

None

Ignore files

None

Raw curl example

curl -s $(baseUrl)/run-clean.sh | bash

---

run-docc-docker.sh

Purpose

Serves generated DocC documentation locally using Docker.

Behavior

• Runs Nginx in the foreground
• Exposes documentation over HTTP

Parameters

• -n <name> – container name
• -p <host:container> – port mapping

Ignore files

None

Raw curl example

curl -s $(baseUrl)/run-docc-docker.sh | bash -s -- -p 8800:80

---

run-openapi-docker.sh

Purpose

Serves OpenAPI documentation locally using Docker.

Behavior

• Runs Nginx in the foreground
• Exposes documentation over HTTP

Parameters

• -n <name> – container name
• -p <host:container> – port mapping

Ignore files**

None

Raw curl example**

curl -s $(baseUrl)/run-openapi-docker.sh | bash -s -- -n openapi-preview

---

run-swift-format.sh

Purpose

Runs swift-format to lint or format Swift source files.

Behavior

• Downloads default configuration if missing
• Respects ignore rules
• Supports parallel execution

Parameters

• --fix – format files in-place

Ignore files

• .swiftformatignore – excludes files from formatting

Raw curl examples

Lint only:

curl -s $(baseUrl)/run-swift-format.sh | bash

Fix formatting:

curl -s $(baseUrl)/run-swift-format.sh | bash -s -- --fix