From 8e8c1d5ed48e0a70e900be0b4757b4d03b7f7eea Mon Sep 17 00:00:00 2001 From: Bassam Khouri Date: Mon, 26 Oct 2026 14:55:20 -0400 Subject: [PATCH] Soundness: add pre-build command input for API breakage check Add an `api_breakage_pre_build_command` workflow_call input that runs as a step before the API breakage check job, allowing callers to run setup commands (e.g. generating sources) that the diagnose-api-breaking-changes step depends on. --- .github/workflows/soundness.yml | 7 +++++++ docs/soundness-api-breakage-check.md | 22 ++++++++++++++++++---- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/.github/workflows/soundness.yml b/.github/workflows/soundness.yml index 4b2407dd..43b0f2c7 100644 --- a/.github/workflows/soundness.yml +++ b/.github/workflows/soundness.yml @@ -11,6 +11,10 @@ on: type: string description: "Path to a file that will be passed as --breakage-allowlist-path to swift package diagnose-api-breaking-changes" default: "" + api_breakage_pre_build_command: + type: string + description: "Execute before running the AOU breakage check" + default: "" api_breakage_check_baseline: type: string description: "The tag against which API breakages that should be used as the baseline for the API breakage check. By default the PR base is used." @@ -154,6 +158,9 @@ jobs: - name: Mark the workspace as safe # https://github.com/actions/checkout/issues/766 run: git config --global --add safe.directory ${GITHUB_WORKSPACE} + - name: Pre-build + # zizmor: ignore[template-injection] + run: ${{ inputs.api_breakage_pre_build_command }} - name: Run API breakage check shell: bash env: diff --git a/docs/soundness-api-breakage-check.md b/docs/soundness-api-breakage-check.md index 23717238..f659e7fc 100644 --- a/docs/soundness-api-breakage-check.md +++ b/docs/soundness-api-breakage-check.md @@ -8,11 +8,12 @@ The job fails when the command reports API breakages that are not covered by an 1. Checks out the repository with full history, tags, and submodules (`fetch-depth: 0`, `fetch-tags: true`). Credentials are persisted because `diagnose-api-breaking-changes` clones the repository again, which would otherwise fail for private repositories. 2. Marks the workspace as a safe git directory. -3. Runs `linux_pre_build_command`, if provided. -4. Determines the **baseline** to compare against: +3. Runs `api_breakage_pre_build_command`, if provided, in its own step. +4. Runs `linux_pre_build_command`, if provided, immediately before the check itself. +5. Determines the **baseline** to compare against: - if `api_breakage_check_baseline` is set, that tag or ref is used; - otherwise the pull request's base branch (`GITHUB_BASE_REF`) is fetched into a local `pull-base-ref` ref and used. -5. Runs `swift package diagnose-api-breaking-changes `, adding `--breakage-allowlist-path ` when `api_breakage_check_allowlist_path` is set, followed by any `api_breakage_check_additional_arguments`. +6. Runs `swift package diagnose-api-breaking-changes `, adding `--breakage-allowlist-path ` when `api_breakage_check_allowlist_path` is set, followed by any `api_breakage_check_additional_arguments`. The job has a 40 minute timeout. @@ -45,6 +46,7 @@ jobs: |---|---|---|---| | `api_breakage_check_enabled` | boolean | `true` | Enable or disable the job. | | `api_breakage_check_allowlist_path` | string | `""` | Path to a file passed as `--breakage-allowlist-path`. Relative paths are resolved from the repository root. | +| `api_breakage_pre_build_command` | string | `""` | Shell command run in its own step before the baseline is determined and the check runs (e.g., generating sources the check depends on). | | `api_breakage_check_baseline` | string | `""` | Tag or ref to compare against. When empty, the pull request's base branch is used. | | `api_breakage_check_container_image` | string | `swift:6.3-noble` | Docker image used to run the check. | | `api_breakage_check_additional_arguments` | string | `""` | Extra arguments appended to the `swift package diagnose-api-breaking-changes` invocation. | @@ -101,6 +103,18 @@ jobs: linux_pre_build_command: "apt-get update && apt-get install -y libxml2-dev" ``` +### Run a command before the check + +Use `api_breakage_pre_build_command` to run setup the check itself depends on, such as generating sources: + +```yaml +jobs: + soundness: + uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main + with: + api_breakage_pre_build_command: "swift run generate-sources" +``` + ### Disable the check Packages that expose no public API (for example, executables only) can turn the job off: @@ -121,5 +135,5 @@ jobs: | The baseline tag is not found. | The tag does not exist in the repository. Tags are fetched by the checkout step, so confirm the name matches exactly. | | Job fails on a breakage you intend to make. | Add the reported breakage to the allowlist file referenced by `api_breakage_check_allowlist_path`. | | Allowlist file is not found. | The path is resolved from the repository root, not from the workflow file's location. | -| Build fails before the comparison runs. | A system dependency is missing. Install it with `linux_pre_build_command`. | +| Build fails before the comparison runs. | A system dependency is missing. Install it with `linux_pre_build_command`, or `api_breakage_pre_build_command` if the setup is specific to this job. | | Job fails to clone the repository (private repositories). | The checkout step must persist credentials. The workflow already does this, so check that the calling workflow grants `contents: read`. |