Setting up oasdiff Pro

Two steps to get an encrypted side-by-side review and a breaking-change gate on every pull request that changes your API.

Get your token

Visit oasdiff.com/start-trial. It signs you in with GitHub and activates a 30-day Pro trial (no credit card). Your OASDIFF_TOKEN is shown on your setup page.

1. Add your OASDIFF_TOKEN as a repository secret

In your repo, go to Settings → Secrets and variables → Actions → New repository secret. Name it OASDIFF_TOKEN and paste the value from your setup page.

2. Add the workflow

Create .github/workflows/oasdiff.yml with this content. Set the path to your OpenAPI spec and the snippet updates to match.

name: oasdiff

# On every pull request, oasdiff posts an encrypted side-by-side review
# comment and sets the "oasdiff" merge gate.
on:
  pull_request:
    branches: [ "main" ]

permissions:
  pull-requests: write   # post the review comment
  statuses: write        # set the merge-gate commit status

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: oasdiff/oasdiff-action/changelog@v0
        with:
          base: 'origin/${{ github.base_ref }}:openapi.yaml'
          revision: 'HEAD:openapi.yaml'
          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}
          github-token: ${{ github.token }}

The permissions block lets the action post the review comment and set the oasdiff merge-gate status with the workflow's built-in GITHUB_TOKEN.

Optional: install the GitHub App

Not required, the workflow above already posts the review and sets the gate. Install the oasdiff GitHub App for an instant gate (it updates the moment a change is approved, instead of on the next CI run) and for reviews on pull requests from forks.

What happens next

Open a pull request that changes your spec. oasdiff posts an encrypted side-by-side review comment and sets the oasdiff breaking-change gate. Your 30-day Pro trial starts automatically when that first review posts. Each reviewer on your team can approve or reject every change from the review page; the gate stays pending until all breaking changes are approved, then flips to success (instantly with the GitHub App installed, otherwise on the next CI run). Approvals carry forward: if the same change appears in a later commit, it stays approved.

Optional but recommended: branch protection

To actually block merges, add oasdiff to the required status checks on your protected branches. Without it the commit status is informational only and won't prevent merging.

Your specs are encrypted client-side

The action encrypts both specs and the computed changelog in CI before upload, and the decryption key travels only in the review link's URL fragment, which browsers never send to a server. oasdiff stores only ciphertext it cannot read; anyone with the link can open the review. For the full data inventory, see the privacy policy.

Need your spec content to never leave your own GitHub? That is available on oasdiff Enterprise, where reviews load specs live from GitHub with each reviewer's own access and nothing is uploaded or stored.

Common questions

Do I have to install the GitHub App?

No. The action posts the review and sets the gate with the workflow's built-in GITHUB_TOKEN. The App is an optional upgrade for an instant gate and fork pull requests, and you can add it later with no change to your workflow.

Who can approve changes?

Anyone on your oasdiff team (invite up to 5 reviewers on Pro). Reviewers sign in on oasdiff.com; approval is gated on your oasdiff team, not on GitHub repository access.

Do I have to start a trial to use oasdiff?

No. The CLI and the free GitHub Action need no account. The Pro trial only starts when you visit oasdiff.com/start-trial and post your first Pro review.

Next steps

Questions? Email info@oasdiff.com.