{"id":21846590,"url":"https://github.com/binarybirds/github-workflows","last_synced_at":"2026-04-13T06:45:54.261Z","repository":{"id":259056809,"uuid":"876065379","full_name":"BinaryBirds/github-workflows","owner":"BinaryBirds","description":"A reusable workflow and various bash scripts","archived":false,"fork":false,"pushed_at":"2024-11-22T11:56:23.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-19T13:17:13.263Z","etag":null,"topics":["bash","github-action","swift"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BinaryBirds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-21T10:44:16.000Z","updated_at":"2024-11-22T11:56:27.000Z","dependencies_parsed_at":"2024-11-18T14:04:16.887Z","dependency_job_id":"b5e95f5a-8430-4278-ad97-64f4ff0a1922","html_url":"https://github.com/BinaryBirds/github-workflows","commit_stats":null,"previous_names":["binarybirds/github-workflows"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryBirds%2Fgithub-workflows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryBirds%2Fgithub-workflows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryBirds%2Fgithub-workflows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryBirds%2Fgithub-workflows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BinaryBirds","download_url":"https://codeload.github.com/BinaryBirds/github-workflows/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244831061,"owners_count":20517620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","github-action","swift"],"created_at":"2024-11-27T23:14:36.404Z","updated_at":"2026-04-13T06:45:54.255Z","avatar_url":"https://github.com/BinaryBirds.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Actions Workflows\n\nThis 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.\n\nThe workflows build on the official [swiftlang/github-workflows](https://github.com/swiftlang/github-workflows) and extend them with additional soundness, documentation, and tooling checks.\n\nThese 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.\n\nIf you are not familiar with GitHub Actions, refer to the official documentation before using or customizing these workflows:\n[GitHub Actions documentation](https://docs.github.com/en/actions)\n\n## Install\n\nNo installation required.\n\nAll scripts are executed directly via `curl | bash` or through the provided `Makefile`.\n\n## Workflows\n\nThis section details the reusable workflows provided by the repository.\n\n### 1. Extra Soundness Workflow (`extra_soundness.yml`)\n\nThis workflow provides configurable, robust checks and testing:\n\n* **Optional Local Swift Dependency Checks**: Checks for accidental `.package(path:)` usage.\n* **Optional Swift Headers Check**: Validates Swift source file headers using a strict 5-line format and respects `.swiftheaderignore`.\n* **Optional DocC Warnings Check**: Runs DocC analysis with `--warnings-as-errors` and fails on warnings.\n* **Optional Swift Test Execution**: Runs tests with optional **`.build` caching** for efficiency.\n* **Optional Swift Package Validation**: Validates Swift package structure, settings, and conventions to ensure consistency.\n* **Multi-Version Support**: Tests across multiple Swift versions, configurable via input (defaulting to `[\"6.0\", \"6.1\"]`).\n* **SSH Support**: Includes steps to set up **SSH credentials** (via the `SSH_PRIVATE_KEY` secret) for projects relying on private Git dependencies.\n\n#### Workflow Inputs\n\n| Input | Description | Default |\n| ------ | ------------ | --------- |\n| `local_swift_dependencies_check_enabled` | Enables local Swift dependency check | `false` |\n| `headers_check_enabled` | Enables Swift headers validation | `false` |\n| `docc_warnings_check_enabled` | Enables DocC warnings check | `false` |\n| `run_tests_with_cache_enabled` | Enables the Swift test job | `false` |\n| `tests_cache_enabled` | Enables `.build` cache restore/save in the Swift test job | `true` |\n| `run_tests_swift_versions` | Swift versions to test | `[\"6.1\",\"6.2\"]` |\n| `swift_package_validation_enabled` | Runs Swift package validation in the repository. | `false` |\n\n#### Example Usage (Caller Repository)\n\n```yaml\njobs:\n  soundness:\n    uses: BinaryBirds/github-workflows/.github/workflows/extra_soundness.yml@main\n    with:\n      local_swift_dependencies_check_enabled: true\n      headers_check_enabled: true\n      docc_warnings_check_enabled: true\n      run_tests_with_cache_enabled: true\n      tests_cache_enabled: true\n      run_tests_swift_versions: '[\"6.1\",\"6.2\"]'\n      swift_package_validation_enabled: true\n```\n\n### 2. DocC Deploy Workflow (`docc_deploy.yml`)\n\nThis workflow handles the generation and deployment of DocC documentation:\n\n* **Builds DocC Documentation**: Uses a Swift 6.2 Docker image to build the documentation.\n* **Deploys to GitHub Pages**: Uses `actions/deploy-pages@v6` to publish the results.\n* **Target Configuration**: Respects `.docctargetlist` if present.\n\n#### Example Usage (Caller Repository)\n\n```yaml\njobs:\n  create-docc-and-deploy:\n    uses: BinaryBirds/github-workflows/.github/workflows/docc_deploy.yml@main\n    permissions:\n      contents: read\n      pages: write\n      id-token: write\n```\n\n### 3. API Breaking Changes Workflow (`api_breakage.yml`)\n\nThis workflow checks for API breaking changes in the repository:\n\n* Runs API Breakage Checks: Executes the Binary Birds API breakage checking script.\n* Swift-based Environment: Runs inside a swift:latest Docker container.\n* Full Git History Available: Checks out the repository with complete history for accurate comparison.\n\n#### Example Usage (Caller Repository)\n\n```yaml\njobs:\n  check-api-breakage:\n    uses: BinaryBirds/github-workflows/.github/workflows/api_breakage.yml@main\n```\n\n-----\n\n## Makefile Usage\n\nA **Makefile** is included to simplify the execution of all automation tasks by converting long `curl | bash` commands into short, memorable `make` targets.\n\n### Combined Makefile Commands\n\nSome Makefile targets group multiple related checks into a single command.\nThese 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.\n\n### Benefits\n\n* Standardizes script usage and ensures consistent options.\n* Shortens long commands into memorable tasks.\n* Supports composite commands and reduces human error.\n\n-----\n\n## Available Scripts Documentation\n\nThe `Makefile` uses the variable `baseUrl` which points to the source of all scripts:\n`https://raw.githubusercontent.com/BinaryBirds/github-workflows/refs/heads/main/scripts`\n\n### DocC dependency placeholder requirement\n\nDocC-related scripts rely on a placeholder inside `Package.swift` to safely inject the `swift-docc-plugin` dependency when needed.\n\nYour `Package.swift` must contain a top-level `dependencies` section (even if empty) and include the following comment:\n\n```swift\n// [docc-plugin-placeholder]\n```\n\nThis placeholder defines the only supported injection point. If either the dependencies section or the placeholder is missing, DocC scripts will fail intentionally.\n\n```swift\ndependencies: [\n    // [docc-plugin-placeholder]\n]\n```\n\nThe placeholder itself has no effect on builds and does not modify target-level dependencies.\n\n### check-api-breakage.sh\n\n#### Purpose\n\nDetects source- and binary-level API breaking changes in Swift packages to prevent unintended public API regressions.\n\n#### Behavior\n\n* Uses `swift package diagnose-api-breaking-changes`\n* Pull requests: fetches `${GITHUB_BASE_REF}` into a local `pull-base-ref` and compares against that ref\n* Other contexts: fetches tags and compares against the latest Git tag\n* If no tags exist, exits successfully with a warning\n* Fails when breaking changes are detected\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/check-api-breakage.sh | bash\n```\n\n---\n\n### check-broken-symlinks.sh\n\n#### Purpose\n\nEnsures all git-tracked symbolic links resolve to valid targets.\n\n#### Behavior\n\n* Inspects only symbolic links\n* Ignores regular missing files\n* Reports each broken symlink explicitly\n* Exits non-zero if any broken symlink is found\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/check-broken-symlinks.sh | bash\n```\n\n---\n\n### check-docc-warnings.sh\n\n#### Purpose\n\nRuns DocC documentation analysis in strict mode, treating warnings as errors.\n\n#### Behavior\n\n* Uses `.docctargetlist` when present, otherwise auto-detects targets\n* Temporarily injects `swift-docc-plugin` if missing\n* Requires a clean git working tree locally\n* Restores git state after execution\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n* `.docctargetlist` – explicitly defines documented targets\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/check-docc-warnings.sh | bash\n```\n\n---\n\n### check-local-swift-dependencies.sh\n\n#### Purpose\n\nPrevents accidental usage of local Swift package dependencies.\n\n#### Behavior\n\n* Scans git-tracked `Package.swift` files only (ignores untracked files)\n* Detects `.package(path:)`\n* Fails immediately on detection\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/check-local-swift-dependencies.sh | bash\n```\n\n---\n\n### check-openapi-security.sh\n\n#### Purpose\n\nRuns fast static OpenAPI security lint checks using Spectral.\n\n#### Behavior\n\n* Executes inside Docker\n* Accepts an OpenAPI file or directory (default: `openapi`)\n* Relative `-f` paths are resolved from the git repository root first, then current working directory\n* For file paths, supports `.yml`/`.yaml`/`.json` extension fallback\n* For directory paths, resolves `openapi.yaml`, then `openapi.yml`, then `openapi.json`\n* Performs static linting only (no running API server required)\n* Skips execution if no OpenAPI specification can be resolved\n\n#### Parameters\n\n* `-f \u003cpath\u003e` – OpenAPI file or directory path\n\n#### Ignore files\n\n_None_\n\n#### Raw curl examples\n\n```sh\ncurl -s $(baseUrl)/check-openapi-security.sh | bash\n```\n\n```sh\ncurl -s $(baseUrl)/check-openapi-security.sh | bash -s -- -f openapi/openapi.yml\n```\n\n---\n\n### check-openapi-validation.sh\n\n#### Purpose\n\nValidates an OpenAPI specification for schema correctness.\n\n#### Behavior\n\n* Runs the OpenAPI validator in Docker\n* Accepts an OpenAPI file or directory (default: `openapi`)\n* Relative `-f` paths are resolved from the git repository root first, then current working directory\n* For file paths, supports `.yml`/`.yaml`/`.json` extension fallback\n* For directory paths, resolves `openapi.yaml`, then `openapi.yml`, then `openapi.json`\n* Supports debug tracing via `-d` (prints resolved paths and command trace)\n* Supports `--detailed` to run additional Spectral diagnostics when validation fails\n* Skips execution if no OpenAPI specification can be resolved\n\n#### Parameters\n\n* `-f \u003cpath\u003e` – OpenAPI file or directory path\n* `-d` – enable debug tracing\n* `--detailed` – run additional detailed diagnostics on validation failure\n\n#### Ignore files\n\n_None_\n\n#### Raw curl examples\n\n```sh\ncurl -s $(baseUrl)/check-openapi-validation.sh | bash\n```\n\n```sh\ncurl -s $(baseUrl)/check-openapi-validation.sh | bash -s -- -f openapi/openapi.yaml\n```\n\n```sh\n# Monorepo/nested project example (path relative to git root)\ncurl -s $(baseUrl)/check-openapi-validation.sh | bash -s -- -f mail-examples/mail-example-openapi/openapi/openapi.yaml\n```\n\n---\n\n### check-swift-headers.sh\n\n#### Purpose\n\nEnsures Swift source files contain a consistent, standardized header.\n\n#### Behavior\n\n* Enforces a strict 5-line header format\n* Can optionally insert or update headers in-place\n* Processes only git-tracked Swift files\n* Skips `Package.swift` explicitly\n* Accepts `Created by ... on YYYY. MM. DD.` and legacy `..` suffix\n* In `--fix` mode, normalizes legacy `..` to `.`\n* When repairing malformed headers, preserves extracted author and date when possible\n\n#### Parameters\n\n* `--fix` – insert or update headers automatically\n* `--author \u003cname\u003e` – override default author name\n\n#### Ignore files\n\n* `.swiftheaderignore` – excludes paths from header validation (replaces default exclusions when present)\n\n#### Raw curl examples\n\n_Check only:_\n\n```sh\ncurl -s $(baseUrl)/check-swift-headers.sh | bash\n```\n\n_Fix headers with custom author:_\n\n```sh\ncurl -s $(baseUrl)/check-swift-headers.sh | bash -s -- --fix --author \"John Doe\"\n```\n\n---\n\n### check-unacceptable-language.sh\n\n#### Purpose\n\nDetects discouraged or outdated terminology to promote inclusive language.\n\n#### Behavior\n\n* Case-insensitive, whole-word matching\n* Scans git-tracked files only\n* Lines containing `ignore-unacceptable-language` are excluded from failures\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n* `.unacceptablelanguageignore` – excludes paths from scanning\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/check-unacceptable-language.sh | bash\n```\n\n---\n\n### generate-contributors-list.sh\n\n#### Purpose\n\nGenerates a CONTRIBUTORS.txt file from git commit history.\n\n#### Behavior\n\n* Uses `git shortlog -es HEAD`\n* Respects `.mailmap`\n* Overwrites the file deterministically\n* Writes to repository root even when run from a subdirectory\n* If the repository has no commits, exits successfully and does not create `CONTRIBUTORS.txt`\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/generate-contributors-list.sh | bash\n```\n\n---\n\n### generate-docc.sh\n\n#### Purpose\n\nGenerates DocC documentation into the `docs/` directory.\n\n#### Behavior\n\n* Supports multiple Swift targets\n* Enables combined documentation automatically\n* Can transform output for static hosting\n\n#### Parameters\n\n* `--local` – disable static hosting transform\n* `--name \u003cvalue\u003e` – set hosting base path\n\n#### Ignore files\n\n* `.docctargetlist` – explicitly defines documented targets\n\n#### Raw curl examples\n\n_GitHub Pages output:_\n\n```sh\ncurl -s $(baseUrl)/generate-docc.sh | bash -s -- --name MyRepo\n```\n\n_Local preview:_\n\n```sh\ncurl -s $(baseUrl)/generate-docc.sh | bash -s -- --local\n```\n\n---\n\n### install-swift-format.sh\n\n#### Purpose\n\nInstalls the `swift-format` binary.\n\n#### Behavior\n\n* Builds from source\n* Installs into `/usr/local/bin`\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/install-swift-format.sh | bash\n```\n\n---\n\n### install-swift-openapi-generator.sh\n\n#### Purpose\n\nInstalls the Swift OpenAPI Generator CLI tool.\n\n#### Behavior\n\n* Builds from source\n* Installs the latest available tag by default\n* Supports version pinning via `-v`\n* Validates required tools (`git`, `curl`, `tar`, `swift`, `install`)\n* Uses fail-fast download behavior for release archives\n\n#### Parameters\n\n* `-v \u003cversion\u003e` – install a specific version\n* `-h` – show usage help\n\n#### Ignore files\n\n_None_\n\n#### Raw curl examples\n\n_Latest version:_\n\n```sh\ncurl -s $(baseUrl)/install-swift-openapi-generator.sh | bash\n```\n\n_Specific version:_\n\n```sh\ncurl -s $(baseUrl)/install-swift-openapi-generator.sh | bash -s -- -v 1.2.2\n```\n\n---\n\n### run-clean.sh\n\n#### Purpose\n\nRemoves generated build artifacts and temporary files. ⚠️ Irreversible operation.\n\n#### Behavior\n\n* Deletes `.build/` and `.swiftpm/`\n* Deletes `openapi/openapi.yaml`, `db.sqlite`, and `migration-entries.json`\n* Intended for local development use\n\n\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/run-clean.sh | bash\n```\n\n---\n\n### run-docc-docker.sh\n\n#### Purpose\n\nServes generated DocC documentation locally using Docker.\n\n#### Behavior\n\n* Runs Nginx in the foreground\n* Exposes documentation over HTTP\n\n#### Parameters\n\n* `-n \u003cname\u003e` – container name\n* `-p \u003chost:container\u003e` – port mapping\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/run-docc-docker.sh | bash -s -- -p 8800:80\n```\n\n---\n\n### run-openapi-docker.sh\n\n#### Purpose\n\nServes OpenAPI documentation locally using Docker.\n\n#### Behavior\n\n* Accepts an OpenAPI file or directory (default: `openapi`)\n* Relative `-f` paths are resolved from the git repository root first, then current working directory\n* If a file is provided, mounts its parent directory\n* For file paths, supports `.yml`/`.yaml`/`.json` extension fallback\n* Runs Nginx in the foreground\n* Exposes documentation over HTTP\n\n#### Parameters\n\n* `-n \u003cname\u003e` – container name\n* `-p \u003chost:container\u003e` – port mapping\n* `-f \u003cpath\u003e` – OpenAPI file or directory path\n\n#### Ignore files\n\n_None_\n\n#### Raw curl examples\n\n```sh\ncurl -s $(baseUrl)/run-openapi-docker.sh | bash -s -- -n openapi-preview\n```\n\n```sh\ncurl -s $(baseUrl)/run-openapi-docker.sh | bash -s -- -n openapi-preview -f openapi/openapi.yaml\n```\n\n---\n\n### run-swift-format.sh\n\n#### Purpose\n\nRuns `swift-format` to lint or format Swift source files.\n\n#### Behavior\n\n* Downloads default configuration if missing\n* Respects ignore rules\n* Supports parallel execution\n\n#### Parameters\n\n* `--fix` – format files in-place\n\n#### Ignore files\n\n* `.swiftformatignore` – excludes files from formatting\n\n#### Raw curl examples\n\n_Lint only:_\n\n```sh\ncurl -s $(baseUrl)/run-swift-format.sh | bash\n```\n\n_Fix formatting:_\n\n```sh\ncurl -s $(baseUrl)/run-swift-format.sh | bash -s -- --fix\n```\n\n---\n\n### run-actionlint.sh\n\n#### Purpose\n\nRuns `actionlint` to validate GitHub Actions workflows.\n\n#### Behavior\n\n* Verifies `actionlint` is installed before running\n* Runs from repository root for consistent workflow path resolution\n* Passes through optional CLI arguments to `actionlint`\n\n#### Parameters\n\n* `\u003cactionlint args...\u003e` – optional arguments passed to `actionlint`\n\n#### Ignore files\n\n_None_\n\n#### Raw curl example\n\n```sh\ncurl -s $(baseUrl)/run-actionlint.sh | bash\n```\n\n---\n\n### script-format.sh\n\n#### Purpose\n\nRuns `shfmt` to check or fix formatting for tracked shell-related files.\n\n#### Behavior\n\n* Verifies `shfmt` is installed before running\n* Targets tracked `*.sh`, `*.bash`, and `*.bats` files\n* Default mode checks formatting and fails on drift\n* `--fix` mode applies formatting in-place\n\n#### Parameters\n\n* `--fix` – apply formatting in-place\n\n#### Ignore files\n\n_None_\n\n#### Raw curl examples\n\n_Check only:_\n\n```sh\ncurl -s $(baseUrl)/script-format.sh | bash\n```\n\n_Fix formatting:_\n\n```sh\ncurl -s $(baseUrl)/script-format.sh | bash -s -- --fix\n```\n\n---\n\n### check-swift-package.sh\n\n#### Purpose\n\nValidates Swift package structure and configuration to enforce project-wide conventions.\n\n#### Behavior\n\n* Verifies Package.swift presence and Swift tools version\n* Ensures Swift tools version is 6.1 or newer\n* Requires defaultSwiftSettings usage on all targets\n* Enforces presence of the NonisolatedNonsendingByDefault Swift 6 concurrency feature\n* Validates top-level dependencies section and DocC placeholder\n* Checks required directory structure (Sources/, Tests/)\n* Ensures required repository files exist\n* Verifies LICENSE contains the current year\n* Aggregates all violations and fails once at the end\n\n#### Parameters\n\n_None_\n\n#### Ignore files\n\n_None_\n\n#### Raw curl examples\n\n```sh\ncurl -s $(baseUrl)/check-swift-package.sh | bash\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarybirds%2Fgithub-workflows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinarybirds%2Fgithub-workflows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarybirds%2Fgithub-workflows/lists"}