From 178cada2212e39c46e160d7bc113bfd7fca869b2 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sun, 15 Nov 2026 19:58:44 +0200 Subject: [PATCH 1/2] Add the Pro token to breaking, fail-on to changelog, and a config input With an oasdiff-token, the breaking action is now the Pro action: it uploads an authenticated review of the breaking changes, posts the review comment and sets the oasdiff commit status. Pro used to exist only on changelog, so a workflow built on breaking had to switch actions to upgrade. changelog takes fail-on. Its script captured oasdiff's exit code and never returned it, so a changelog could not fail a job, and a fail-on in .oasdiff.yaml was ignored there while level from the same file was honored. It now exits with that code. Both actions take config, the path to an oasdiff config file, for a repository that does not keep .oasdiff.yaml at its root. The README said github-token defaults to an empty string; action.yml has defaulted it to the job's token all along. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/test-breaking.yaml | 116 ++++++++++++++++++++++++++ .github/workflows/test-changelog.yaml | 54 ++++++++++++ README.md | 16 ++-- breaking/action.yml | 8 ++ breaking/entrypoint.sh | 44 +++++++--- changelog/action.yml | 8 ++ 6 files changed, 228 insertions(+), 18 deletions(-) diff --git a/.github/workflows/test-breaking.yaml b/.github/workflows/test-breaking.yaml index 8542ff3..fbbf8e8 100644 --- a/.github/workflows/test-breaking.yaml +++ b/.github/workflows/test-breaking.yaml @@ -559,3 +559,119 @@ jobs: exit 1 fi echo "PASS" + + oasdiff_breaking_config_input: + runs-on: ubuntu-latest + name: Test breaking action reads the config file the config input names + steps: + - name: checkout + uses: actions/checkout@v7 + - name: Put a config file somewhere other than the repo root + run: | + mkdir -p ci + cat > ci/oasdiff.yaml <&2 + exit 1 + fi + + oasdiff_breaking_pro_posts_comment_and_status: + runs-on: ubuntu-latest + name: Test breaking Pro path posts the review comment and sets the gate + # With an oasdiff-token the breaking action is the Pro action: it uploads + # an authenticated review of the breaking changes, posts the review + # comment and sets the oasdiff commit status. Stubs oasdiff (one change in + # the json render; --open prints a /review/ep URL and a pending status) + # and curl (keeps the comment body). + steps: + - uses: actions/checkout@v7 + - name: Stub oasdiff + curl (Pro success), run entrypoint + run: | + set -euo pipefail + mkdir -p /tmp/stub /tmp/run + + cat > /tmp/stub/oasdiff <<'STUB' + #!/bin/sh + for a in "$@"; do [ "$a" = "json" ] && { printf '[{"id":"api-removed-without-deprecation","text":"API removed","level":3,"operation":"GET","path":"/pets","section":"paths"}]'; exit 0; }; done + for a in "$@"; do + if [ "$a" = "--open" ]; then + echo "$1" > /tmp/run/open-command + echo "oasdiff: opening review at https://www.oasdiff.com/review/ep/test-token-uuid#k=test-key" >&2 + echo "oasdiff: review status: pending" >&2 + exit 0 + fi + done + echo "1 changes: 1 error, 0 warning, 0 info" + STUB + chmod +x /tmp/stub/oasdiff + + cat > /tmp/stub/curl <<'STUB' + #!/bin/sh + for a in "$@"; do + case "$a" in *"%{http_code}"*) http_code=1 ;; esac + case "$a" in *"/issues/"*) comment=1 ;; esac + case "$a" in *"/statuses/"*) status=1 ;; esac + done + if [ -n "${http_code:-}" ]; then + if [ -n "${comment:-}" ]; then cat > /tmp/run/pro-comment.json + elif [ -n "${status:-}" ]; then cat > /tmp/run/status.json + else cat > /dev/null; fi + echo "201" + exit 0 + fi + echo "[]" + STUB + chmod +x /tmp/stub/curl + + export GITHUB_REF=refs/pull/123/merge + export GITHUB_REPOSITORY=acme/widgets + export GITHUB_SHA=deadbeef + export GITHUB_OUTPUT=/tmp/run/out; : > "$GITHUB_OUTPUT" + export GITHUB_STEP_SUMMARY=/tmp/run/summary; : > "$GITHUB_STEP_SUMMARY" + cat > /tmp/run/event.json <&1) + echo "--- output ---"; echo "$out" + + if [ "$(cat /tmp/run/open-command)" != "breaking" ]; then + echo "FAIL: the Pro review was not uploaded by 'oasdiff breaking'" >&2; exit 1 + fi + pro_body=$(jq -r '.body' < /tmp/run/pro-comment.json) + echo "--- Pro comment body ---"; echo "$pro_body" + for expected in \ + '1 breaking change in this pull request' \ + 'Review required' \ + '| severity | change | endpoint |' \ + 'api-removed-without-deprecation' \ + 'Review and approve the changes' + do + case "$pro_body" in + *"$expected"*) ;; + *) echo "FAIL: the Pro comment is missing: $expected" >&2; exit 1 ;; + esac + done + if [ "$(jq -r '.state' < /tmp/run/status.json)" != "pending" ]; then + echo "FAIL: the oasdiff commit status was not set to pending" >&2; exit 1 + fi + if ! grep -q "review/ep/test-token-uuid" "$GITHUB_STEP_SUMMARY"; then + echo "FAIL: review URL not in step summary" >&2; exit 1 + fi + echo "PASS" diff --git a/.github/workflows/test-changelog.yaml b/.github/workflows/test-changelog.yaml index f1a960a..f5315d1 100644 --- a/.github/workflows/test-changelog.yaml +++ b/.github/workflows/test-changelog.yaml @@ -373,3 +373,57 @@ jobs: exit 1 fi echo "PASS" + + oasdiff_changelog_fail_on: + runs-on: ubuntu-latest + name: Test changelog action fails the job on fail-on + steps: + - name: checkout + uses: actions/checkout@v7 + - name: Running changelog action with fail-on + id: test_fail_on + continue-on-error: true + uses: ./changelog + with: + base: 'specs/base.yaml' + revision: 'specs/revision.yaml' + fail-on: ERR + review: false + - name: Assert the step failed and still produced the changelog + env: + ACTUAL_OUTPUT: ${{ steps.test_fail_on.outputs.changelog }} + run: | + if [ "${{ steps.test_fail_on.outcome }}" != "failure" ]; then + echo "Expected the step to fail on fail-on: ERR. Got: ${{ steps.test_fail_on.outcome }}" >&2 + exit 1 + fi + case "$ACTUAL_OUTPUT" in + *" changes: "*) ;; + *) echo "Expected the changelog output alongside the failure, got: '$ACTUAL_OUTPUT'" >&2; exit 1 ;; + esac + + oasdiff_changelog_yaml_config_fail_on: + runs-on: ubuntu-latest + name: Test changelog action picks up fail-on from .oasdiff.yaml + steps: + - name: checkout + uses: actions/checkout@v7 + - name: Drop .oasdiff.yaml at repo root + run: | + cat > .oasdiff.yaml <&2 + exit 1 + fi diff --git a/README.md b/README.md index 214c867..7ed1920 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,8 @@ jobs: | `output-to-file` | `''` | Write output to this file path instead of stdout | file path | | `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs or loads split files by file path | `true`, `false` | | `review` | `true` | When changes are found, upload the comparison to oasdiff.com and link to a direct side-by-side review. The two specs are encrypted in CI before upload and the decryption key stays in the URL fragment, so the server cannot read them. Set `false` to skip the upload, so no spec leaves CI | `true`, `false` | -| `github-token` | `''` | Token used to post the changes as a pull-request comment, so reviewers see them on the PR instead of only in the job summary. Pass `${{ github.token }}` and grant `permissions: pull-requests: write`. Optional; omit it to keep the link in the job summary only. Fork PRs (read-only token) fall back to the summary | `${{ github.token }}` | +| `github-token` | `${{ github.token }}` | Token used to post the changes as a pull-request comment, so reviewers see them on the PR instead of only in the job summary. The default is the job's own token, so you only need to grant `permissions: pull-requests: write`. Set it to an empty string to keep the link in the job summary only. Fork PRs (read-only token) fall back to the summary | a token, or `''` | +| `config` | `''` | Path to an oasdiff config file, for a repository that does not keep `.oasdiff.yaml` at its root | a file path | ### Generate a changelog @@ -145,6 +146,7 @@ jobs: | `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref | | `format` | `''` | Output format | `text`, `json`, `yaml`, `markdown`, `html` | | `level` | `''` | Minimum severity level to include in output | `INFO`, `WARN`, `ERR` | +| `fail-on` | `''` | Fail with exit code 1 when a change is at or above this severity. Empty never fails | `ERR`, `WARN`, `INFO`, `MISSING-VERSION-BUMP` | | `include-path-params` | `false` | Include path parameter names in endpoint matching | `true`, `false` | | `exclude-elements` | `''` | Exclude certain kinds of changes from the output | `endpoints`, `request`, `response` (comma-separated) | | `filter-extension` | `''` | Exclude paths and operations with an OpenAPI Extension matching this expression | regex | @@ -157,7 +159,8 @@ jobs: | `output-to-file` | `''` | Write output to this file path instead of stdout | file path | | `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs or loads split files by file path | `true`, `false` | | `review` | `true` | When changes are found, upload the comparison to oasdiff.com and link to a direct side-by-side review. The two specs are encrypted in CI before upload and the decryption key stays in the URL fragment, so the server cannot read them. Set `false` to skip the upload, so no spec leaves CI | `true`, `false` | -| `github-token` | `''` | Token used to post the changes as a pull-request comment, so reviewers see them on the PR instead of only in the job summary. Pass `${{ github.token }}` and grant `permissions: pull-requests: write`. Optional; omit it to keep the link in the job summary only. Fork PRs (read-only token) fall back to the summary | `${{ github.token }}` | +| `github-token` | `${{ github.token }}` | Token used to post the changes as a pull-request comment, so reviewers see them on the PR instead of only in the job summary. The default is the job's own token, so you only need to grant `permissions: pull-requests: write`. Set it to an empty string to keep the link in the job summary only. Fork PRs (read-only token) fall back to the summary | a token, or `''` | +| `config` | `''` | Path to an oasdiff config file, for a repository that does not keep `.oasdiff.yaml` at its root | a file path | ### Generate a diff report @@ -294,7 +297,7 @@ When using git refs, you need to check out the repo and fetch the base branch: ## Pro: Approve and gate changes -oasdiff Pro adds a sign-off step to the review, so a breaking change can't merge until your team approves it. It's the **same `changelog` action** as above, with your `oasdiff-token` added. +oasdiff Pro adds a sign-off step to the review, so a breaking change can't merge until your team approves it. It's the **same action you already run**, `breaking` or `changelog`, with your `oasdiff-token` added. On every pull request, oasdiff posts the encrypted side-by-side review and gives each change **Approve / Reject** buttons. A commit status check named `oasdiff` blocks the merge until every breaking change is approved. Approvals are tied to the change fingerprint and carry forward across commits, with a record of who approved what and when. @@ -314,17 +317,16 @@ jobs: steps: - uses: actions/checkout@v7 - run: git fetch --depth=1 origin ${{ github.base_ref }} - - uses: oasdiff/oasdiff-action/changelog@v0 + - uses: oasdiff/oasdiff-action/breaking@v0 with: base: 'origin/${{ github.base_ref }}:openapi.yaml' revision: 'HEAD:openapi.yaml' oasdiff-token: ${{ secrets.OASDIFF_TOKEN }} - github-token: ${{ github.token }} ``` -The only difference from the free [changelog workflow](#generate-a-changelog) is the `oasdiff-token` secret and the `statuses: write` permission. Your specs are still encrypted in CI before upload, so the server can't read them. +The only difference from the free [breaking workflow](#check-for-breaking-changes) is the `oasdiff-token` secret and the `statuses: write` permission. Your specs are still encrypted in CI before upload, so the server can't read them. With `breaking`, the changes to approve are the breaking ones; use `changelog` with the same token to put every change up for review. -This is the `changelog` action [documented above](#generate-a-changelog); the one added input is: +Both actions are documented above; the one added input is: | Input | Default | Description | Accepted values | |---|---|---|---| diff --git a/breaking/action.yml b/breaking/action.yml index 7afda96..83256dd 100644 --- a/breaking/action.yml +++ b/breaking/action.yml @@ -64,6 +64,14 @@ inputs: description: 'GitHub token used to post the review link as a pull-request comment, so reviewers see it on the PR instead of only in the job summary. Defaults to the built-in github.token, so the comment is posted automatically when the job grants permissions: pull-requests: write. Set to an empty string to disable the comment (the link then appears only in the job summary). On fork pull requests the token is read-only, so commenting is skipped and the link falls back to the job summary.' required: false default: ${{ github.token }} + oasdiff-token: + description: 'Your oasdiff Pro token (the OASDIFF_TOKEN secret). When set, the action uploads an authenticated review, posts the approve/reject comment, and sets the `oasdiff` commit status check that gates the merge. Requires permissions: pull-requests: write and statuses: write.' + required: false + default: '' + config: + description: 'Path to an oasdiff config file, for a repository that does not keep .oasdiff.yaml at its root' + required: false + default: '' outputs: breaking: description: 'Output summary of API breaking changes, encompassing both warnings and errors' diff --git a/breaking/entrypoint.sh b/breaking/entrypoint.sh index fd5d431..14e77af 100755 --- a/breaking/entrypoint.sh +++ b/breaking/entrypoint.sh @@ -44,11 +44,12 @@ allow_external_refs=$(input allow-external-refs) review=$(input review) github_token=$(input github-token) oasdiff_token=$(input oasdiff-token) +config=$(input config) readonly base revision fail_on include_checks include_path_params \ deprecation_days_beta deprecation_days_stable exclude_elements \ filter_extension composed flatten_allof err_ignore warn_ignore \ output_to_file prefix_base prefix_revision case_insensitive_headers \ - format template level allow_external_refs review github_token oasdiff_token + format template level allow_external_refs review github_token oasdiff_token config # What the PR comment calls the changes this command reports. case "$oasdiff_command" in @@ -272,7 +273,7 @@ pro_review () { # Tolerate a non-zero exit; --open is additive. --review-meta carries the PR # context as an opaque bag the CLI forwards without interpreting. # shellcheck disable=SC2086 # the flags variables hold multiple arguments; splitting is intended - pro_out=$(oasdiff changelog "$base" "$revision" $flags --open --template= \ + pro_out=$(oasdiff "$oasdiff_command" "$base" "$revision" $flags --open --template= \ --review-token "$oasdiff_token" \ --review-meta owner="$owner" \ --review-meta repo="$repo" \ @@ -328,12 +329,12 @@ pro_comment () { | jq -r --arg m "$marker" 'map(select(.body | contains($m))) | .[0].id // empty' 2>/dev/null) || existing_id="" if [ "${change_count:-0}" -eq 1 ]; then - heading="1 API change in this pull request" + heading="1 ${change_noun} in this pull request" else - heading="${change_count:-0} API changes in this pull request" + heading="${change_count:-0} ${change_noun}s in this pull request" fi body="${marker} -### 📋 ${heading} +### ${comment_icon} ${heading} ${status_line} @@ -412,7 +413,7 @@ pro_review_clear () { | jq -r --arg m "$marker" 'map(select(.body | contains($m))) | .[0].id // empty' 2>/dev/null) || existing_id="" [ -z "$existing_id" ] && return 0 body="${marker} -### ✅ No API changes in the latest revision." +### ✅ ${no_changes_comment}" payload=$(jq -n --arg body "$body" '{body: $body}') printf '%s' "$payload" | curl -s -o /dev/null -X PATCH \ -H "Authorization: token $github_token" \ @@ -461,6 +462,9 @@ run_breaking () { if [ -n "$warn_ignore" ]; then flags="$flags --warn-ignore $warn_ignore" fi + if [ -n "$config" ]; then + flags="$flags --config $config" + fi echo "flags: $flags" # Run 1: capture the default-format report and the exit code, applying @@ -540,7 +544,15 @@ run_breaking () { # stores a blob it cannot read. Set review: false to skip the upload # entirely, so no spec ever leaves CI; the breaking-change detection and # the inline annotations are unaffected either way. - if [ "$review" != "false" ]; then + if [ -n "$oasdiff_token" ]; then + # Pro: an authenticated review with an approval gate, posted instead + # of the free one (one review per pull request). + if [ "$composed" = "true" ]; then + echo "::notice::oasdiff: the side-by-side review isn't available in composed mode (-c). The breaking-change report above is unaffected." + else + pro_review + fi + elif [ "$review" != "false" ]; then if [ "$composed" = "true" ]; then # Composed mode (-c) diffs globs of many files; the side-by-side # review represents exactly two specs, so --open can't build it. @@ -579,7 +591,9 @@ run_breaking () { write_output "No breaking changes" # Keep an existing review comment honest when a later push fixes the # breaking changes; never create one for an always-clean PR. - if [ "$review" != "false" ]; then + if [ -n "$oasdiff_token" ]; then + pro_review_clear + elif [ "$review" != "false" ]; then post_review_comment "" fi fi @@ -590,7 +604,7 @@ run_breaking () { # review_url is a single-line output, written after the multiline `breaking` # block is closed so it doesn't get folded into that value. Empty when there # are no breaking changes (the notice/URL only fire then). - echo "review_url=${free_review_url:-}" >> "$GITHUB_OUTPUT" + echo "review_url=${free_review_url:-${review_url:-}}" >> "$GITHUB_OUTPUT" exit $exit_code } @@ -645,6 +659,9 @@ run_changelog () { if [ -n "$template" ]; then fmt_flags="$fmt_flags --template $template" fi + if [ -n "$config" ]; then + flags="$flags --config $config" + fi echo "flags: $flags, presentation flags: $fmt_flags" # *** github action step output *** @@ -659,8 +676,12 @@ run_changelog () { exit_code=0 _err=$(mktemp) + fail_on_flag="" + if [ -n "$fail_on" ]; then + fail_on_flag="--fail-on $fail_on" + fi # shellcheck disable=SC2086 # the flags variables hold multiple arguments; splitting is intended - output=$(oasdiff changelog "$base" "$revision" $flags $fmt_flags 2>"$_err") || exit_code=$? + output=$(oasdiff changelog "$base" "$revision" $flags $fmt_flags $fail_on_flag 2>"$_err") || exit_code=$? # Only codes >=2 are real errors. Exit 1 is a fail-on result (the changelog # action has no fail-on input, but .oasdiff.yaml can set one); the changelog # action doesn't gate, so don't let it abort the run or suppress the review below. @@ -767,7 +788,8 @@ run_changelog () { # are no changes (the notice/URL only fire then). echo "review_url=${free_review_url:-${review_url:-}}" >> "$GITHUB_OUTPUT" - # *** github action step output *** + # 1 when fail-on was reached, from the input or from .oasdiff.yaml. + exit "$exit_code" } case "$oasdiff_command" in diff --git a/changelog/action.yml b/changelog/action.yml index 4a93b21..f15ddb4 100644 --- a/changelog/action.yml +++ b/changelog/action.yml @@ -71,6 +71,14 @@ inputs: description: 'oasdiff Pro tenant token (the OASDIFF_TOKEN secret). When set, the action uploads an authenticated review and posts a review comment + an `oasdiff` commit status gate. Requires `permissions: pull-requests: write` and `statuses: write`.' required: false default: '' + fail-on: + description: 'Fail with exit code 1 when a change has this severity or higher (ERR, WARN or INFO), or with MISSING-VERSION-BUMP when breaking changes have no major version increase in info.version. Empty never fails.' + required: false + default: '' + config: + description: 'Path to an oasdiff config file, for a repository that does not keep .oasdiff.yaml at its root' + required: false + default: '' outputs: changelog: description: 'Output summary of API changelog' From bfd9da02184c1be43ef7c36c20c6a458d29169c8 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sun, 15 Nov 2026 20:01:22 +0200 Subject: [PATCH 2/2] Test fail-on against a spec pair that has an error specs/revision.yaml differs from the base by one info-level change, so fail-on: ERR rightly did not fail the job. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/test-changelog.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-changelog.yaml b/.github/workflows/test-changelog.yaml index f5315d1..6a3f7a0 100644 --- a/.github/workflows/test-changelog.yaml +++ b/.github/workflows/test-changelog.yaml @@ -386,7 +386,7 @@ jobs: uses: ./changelog with: base: 'specs/base.yaml' - revision: 'specs/revision.yaml' + revision: 'specs/revision-breaking.yaml' fail-on: ERR review: false - name: Assert the step failed and still produced the changelog @@ -419,7 +419,7 @@ jobs: uses: ./changelog with: base: 'specs/base.yaml' - revision: 'specs/revision.yaml' + revision: 'specs/revision-breaking.yaml' review: false - name: Assert the fail-on in the file failed the step run: |