Free API Change Review

How to use a free oasdiff review URL that someone shared with you, typically from a GitHub Action notice or a colleague's message.

This page covers both perspectives: the user opening a review URL, and the GitHub organization admin who may need to clear a gate so their members can open one. If you're the admin, the "For organization admins" section near the bottom is the short version.

What is a free review?

When the free oasdiff GitHub Action finds breaking changes in a pull request, it emits a clickable link in the workflow output that points to a review URL on oasdiff.com/review. Opening that URL shows the full side-by-side diff between the base and revised OpenAPI specs, with each breaking change highlighted in context. The URL carries owner, repo, base/rev SHAs and base/rev file paths as query parameters, so it only works when followed from the action's notice link or a colleague's share, not by visiting the bare path.

The free review is read-only, you see the diff and the change list, but the approve and reject buttons are locked. To actually act on the changes (sign off, block merge, keep an audit trail), you'd start an oasdiff Pro trial.

Opening a review URL

Three common ways to arrive at one:

• From a pull request. The free action posts a clickable link to $GITHUB_STEP_SUMMARY of the CI run when breaking changes are found. The PR's "Checks" tab shows the link.
• From a colleague. Someone pasted the review URL into Slack, email, or a comment.
• From the URL bar. Constructed manually from owner + repo + base/rev SHAs + base/rev file paths. Not common but supported.

Sign in to review changes

Click Sign in with GitHub on the review page. After OAuth completes you bounce back to the same URL and the diff renders.

oasdiff reads the spec files using your own GitHub access, not a server-side credential, so you can only see specs your GitHub account can already read on github.com. Two implications follow:

• oasdiff requests repository read access on every sign-in from a review page, even for public repos, so you only authorize once and any later private-repo review just works. Click Authorize when GitHub asks. Public repos are readable without this permission, but oasdiff doesn't know which repos you'll view next, so it asks upfront.
• You must be a collaborator on the repo (or a member of the org that owns it). If your account can't open the repo directly on github.com, oasdiff can't show it to you either, ask the repository owner to add you.
• If you have multiple GitHub accounts (work, personal), the one currently signed in to github.com is the one oasdiff will use. To switch, sign out of github.com and back in as the right account, then re-sign-in to oasdiff.

Organizations with an OAuth policy

When you first sign in to oasdiff, GitHub shows two sections on the authorization screen: Personal user data (the information oasdiff is asking to see) and Organization access (a per-organization list of every organization you belong to). For each organization that requires approval for third-party applications, you'll see a Grant or Request button next to its name. Click that button before clicking the green Authorize oasdiff button. This is the single most common cause of getting stuck on a private-repo review: the Authorize button completes the sign-in even if you didn't click Grant/Request, and oasdiff then can't read your organization's repositories.

If your organization enforces SAML single sign-on

Some organizations require an extra single-sign-on step before any third-party app can see their data, on top of the OAuth grant you give oasdiff at sign-in. If yours does, the review page will detect it and show a card with a direct link to your organization's SSO authorization page.

Steps to clear it:

1. Click the SSO link on the oasdiff page. GitHub opens its SSO flow for the org.
2. Complete your organization's single sign-on (usually a redirect to your identity provider, Okta, Azure AD, etc.).
3. Come back to oasdiff and click Refresh access. You may need to sign in to oasdiff again so it picks up your newly SSO-authorized token.

If something else goes wrong, a denied request, a Grant button you can't find, an empty policy page, the full taxonomy of error messages and recovery paths lives in the oasdiff Pro setup guide's troubleshooting section. The recovery paths are the same whether you're viewing a free review or evaluating Pro.

For organization admins

If members of your organization are trying to view free oasdiff reviews and getting stuck, these are the gates you may need to clear:

• Approve the oasdiff OAuth app if your org restricts third-party OAuth apps. Until oasdiff is on the approved list, member tokens are blocked from reading your org's private repos. The OAuth application policy page is where you approve apps.
• Confirm SAML SSO is configured for OAuth apps if your org enforces SSO. Members each need to authorize their personal OAuth token through SSO (per-user step), there's nothing for you to centrally approve, but if SSO isn't set up for OAuth at all, members can't complete the step.
• Make sure the member has read access to the repo, same as any other GitHub access: org member with role-based access, team membership, or outside collaborator. oasdiff reads with each member's own token, so this is GitHub's gate, not oasdiff's.

Nothing else on the org side is required for free reviews. oasdiff has no server-side credential against your organization; spec files are fetched on demand using the viewing member's own GitHub token and discarded after rendering. The oasdiff Pro setup guide covers the additional steps for Pro (installing the GitHub App, adding the workflow file, branch protection) if your team decides to evaluate that.

When to upgrade to Pro

Upgrade when you want:

• Approve / reject decisions that stick. Approvals carry forward across subsequent commits in the PR; the commit-status check on the PR flips from pending to success only after all breaking changes have been reviewed.
• A rich PR comment posted by oasdiff[bot] summarizing every change, with per-change review links right inside the PR.
• Branch protection enforcement, pair the commit-status check with a branch protection rule so breaking changes can't merge without sign-off.
• Audit trail of who approved what and when.

Pro is a 30-day free trial, no credit card. Start one at oasdiff.com/start-trial. The dashboard then walks through installing the GitHub App and adding a workflow file, about ten minutes end to end. See the Pro setup guide for the full walkthrough, including the org-side approvals an enterprise admin may need to do.

Get help

Email info@oasdiff.com with any review-related questions.