From 4c04ab4951c4bb6d8cbdadc93034cde663bd6c6d Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 10 Aug 2026 01:22:17 +0300 Subject: [PATCH] Stop pretending include-checks works, and point it at .oasdiff.yaml Closes #196. oasdiff retired the optional-checks mechanism include-checks drove and now ignores the flag. The actions still advertised it as functional, so the documented way to enforce a check silently did nothing: the user believes a check is enforced, no error appears, and it never fires. That is the worst of the available failure modes, and it is the bug here. The action no longer forwards the flag and emits a warning annotation instead. Forwarding it was pointless, since oasdiff ignores it, and would break outright if the flag is ever removed rather than ignored. The input stays so workflows that set it today keep working. The replacement, severity-levels, is deliberately NOT added as an input. .oasdiff.yaml is the configuration surface these actions converge on, and the inputs are a deliberate subset: 20 of oasdiff's 30 breaking flags have no input, including auto-upgrade, stability-level, match-path and format. Adding one more would grow a surface we intend to stop growing, and every input is another positional argument in a scheme where a mis-ordered index corrupts a run silently. The deprecation message and the README therefore teach the config file, which already worked and needed no code change. Tests: one job configures severity-levels through .oasdiff.yaml and asserts the downgrade takes effect, alongside the existing yaml-config jobs for fail-on and err-ignore. Another passes a check name that does not exist to include-checks and asserts the run is unaffected, which fails if the action ever forwards it again. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/test-breaking.yaml | 64 ++++++++++++++++++++++++++++ README.md | 11 ++++- breaking/action.yml | 2 +- breaking/entrypoint.sh | 2 +- specs/severity-levels.txt | 1 + 5 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 specs/severity-levels.txt diff --git a/.github/workflows/test-breaking.yaml b/.github/workflows/test-breaking.yaml index f5a6e22..80fc579 100644 --- a/.github/workflows/test-breaking.yaml +++ b/.github/workflows/test-breaking.yaml @@ -277,3 +277,67 @@ jobs: echo "Expected 'No breaking changes' (err-ignore from .oasdiff.yaml should suppress findings) but got '$output'" >&2 exit 1 fi + + oasdiff_breaking_yaml_config_severity_levels: + runs-on: ubuntu-latest + name: Test breaking action picks up severity-levels from .oasdiff.yaml + steps: + - name: checkout + uses: actions/checkout@v7 + # specs/severity-levels.txt downgrades api-removed-without-deprecation to + # info, so the one breaking change these specs produce stops being an + # error and fail-on: ERR no longer fails the step. + - name: Drop .oasdiff.yaml at repo root + run: | + cat > .oasdiff.yaml <&2 + exit 1 + fi + + oasdiff_breaking_include_checks_deprecated: + runs-on: ubuntu-latest + name: Test include-checks is warned about, not applied + env: + OASDIFF_ACTION_TEST_EXPECTED_OUTPUT: "1 changes: 1 error, 0 warning, 0 info" + steps: + - name: checkout + uses: actions/checkout@v7 + # include-checks is ignored by oasdiff. The action must not pass it on and + # must not change the result; it only warns. Passing a name that is not a + # real check would fail the run if the action still forwarded it. + - name: Running breaking action with include-checks + id: test_include_checks + continue-on-error: true + uses: ./breaking + with: + base: 'specs/base.yaml' + revision: 'specs/revision-breaking.yaml' + include-checks: 'not-a-real-check' + - name: Assert the run was unaffected + run: | + delimiter=$(cat /proc/sys/kernel/random/uuid | tr -d '-') + output=$(cat <<-$delimiter + ${{ steps.test_include_checks.outputs.breaking }} + $delimiter + ) + if [ "$output" != "$OASDIFF_ACTION_TEST_EXPECTED_OUTPUT" ]; then + echo "Expected output '$OASDIFF_ACTION_TEST_EXPECTED_OUTPUT' (include-checks must be ignored, not forwarded) but got '$output'" >&2 + exit 1 + fi diff --git a/README.md b/README.md index 4161d01..f07b2b6 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ jobs: | `base` | — (required) | Path to the base (old) OpenAPI spec | file path, URL, git ref | | `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref | | `fail-on` | `''` | Fail with exit code 1 if changes are found at or above this severity | `ERR`, `WARN` | -| `include-checks` | `''` | Include optional breaking change checks | check names (comma-separated) | +| `include-checks` | `''` | **Deprecated and ignored.** oasdiff retired the optional-checks mechanism; set `severity-levels` in `.oasdiff.yaml` instead. Setting it emits a warning annotation and has no effect | — | | `include-path-params` | `false` | Include path parameter names in endpoint matching | `true`, `false` | | `deprecation-days-beta` | `31` | Minimum sunset period (days) for deprecation of beta API endpoints | integer | | `deprecation-days-stable` | `180` | Minimum sunset period (days) for deprecation of stable API endpoints | integer | @@ -237,6 +237,15 @@ exclude-elements: - title - summary err-ignore: ./oasdiff-err-ignore.txt +severity-levels: ./oasdiff-levels.txt +``` + +`severity-levels` points at a file that overrides the severity of individual checks, one `check-id level` per line, where level is `err`, `warn`, `info` or `none`. Raise a check to `err` (with `fail-on: ERR`) to make it fail the build, or set it to `none` to silence it: + +``` +# oasdiff-levels.txt +api-version-not-bumped err +api-major-version-not-bumped err ``` The actions read this file from the runner's `$GITHUB_WORKSPACE` (which `actions/checkout` populates), so no extra steps are needed. diff --git a/breaking/action.yml b/breaking/action.yml index 4d81572..d5c3bff 100644 --- a/breaking/action.yml +++ b/breaking/action.yml @@ -12,7 +12,7 @@ inputs: required: false default: '' include-checks: - description: 'Include any of the defined optional breaking changes checks' + description: 'Deprecated and ignored: oasdiff retired the optional-checks mechanism. To make a check fail the build, set severity-levels in .oasdiff.yaml.' required: false include-path-params: description: 'Include path parameter names in endpoint matching' diff --git a/breaking/entrypoint.sh b/breaking/entrypoint.sh index 00dac9a..a636528 100755 --- a/breaking/entrypoint.sh +++ b/breaking/entrypoint.sh @@ -148,7 +148,7 @@ if [ "$include_path_params" = "true" ]; then flags="$flags --include-path-params" fi if [ -n "$include_checks" ]; then - flags="$flags --include-checks $include_checks" + echo "::warning::oasdiff: 'include-checks' is ignored, the optional-checks mechanism it drove was retired. To make a check fail the build, add 'severity-levels: ' to .oasdiff.yaml, listing the check id with level 'err', and set 'fail-on: ERR'." fi if [ -n "$deprecation_days_beta" ]; then flags="$flags --deprecation-days-beta $deprecation_days_beta" diff --git a/specs/severity-levels.txt b/specs/severity-levels.txt new file mode 100644 index 0000000..511bf82 --- /dev/null +++ b/specs/severity-levels.txt @@ -0,0 +1 @@ +api-removed-without-deprecation info