Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 116 additions & 0 deletions .github/workflows/test-breaking.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<EOF
fail-on: ERR
EOF
- name: Running breaking action with the config input and no fail-on input
id: test_config_input
continue-on-error: true
uses: ./breaking
with:
base: 'specs/base.yaml'
revision: 'specs/revision-breaking.yaml'
config: 'ci/oasdiff.yaml'
review: false
- name: Assert the fail-on in that file failed the step
run: |
if [ "${{ steps.test_config_input.outcome }}" != "failure" ]; then
echo "Expected the step to fail: ci/oasdiff.yaml sets fail-on: ERR and the spec has an ERR-level change. Got: ${{ steps.test_config_input.outcome }}" >&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 <<EVT
{"pull_request":{"head":{"sha":"deadbeef"},"base":{"sha":"baadcafe"}}}
EVT
export GITHUB_EVENT_PATH=/tmp/run/event.json
export PATH=/tmp/stub:$PATH

out=$(env OASDIFF_ACTION_COMMAND=breaking INPUT_BASE=b INPUT_REVISION=r \
'INPUT_GITHUB-TOKEN=gh-token' 'INPUT_OASDIFF-TOKEN=oasdiff-token' bash ./breaking/entrypoint.sh 2>&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"
54 changes: 54 additions & 0 deletions .github/workflows/test-changelog.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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-breaking.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 <<EOF
fail-on: ERR
EOF
- name: Running changelog action without a fail-on input
id: test_yaml_fail_on
continue-on-error: true
uses: ./changelog
with:
base: 'specs/base.yaml'
revision: 'specs/revision-breaking.yaml'
review: false
- name: Assert the fail-on in the file failed the step
run: |
if [ "${{ steps.test_yaml_fail_on.outcome }}" != "failure" ]; then
echo "Expected the step to fail: .oasdiff.yaml sets fail-on: ERR. Got: ${{ steps.test_yaml_fail_on.outcome }}" >&2
exit 1
fi
16 changes: 9 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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 |
|---|---|---|---|
Expand Down
8 changes: 8 additions & 0 deletions breaking/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
Loading
Loading