oasdiff Enterprise: keep your specs on-prem

On Enterprise, oasdiff never uploads or stores your spec content. Each review loads the spec live from GitHub using the reviewer's own access, so spec access strictly follows their GitHub permissions and nothing is stored on oasdiff. This guide covers the GitHub approvals that model needs, plus a troubleshooting table for every message the review page can show.

This is an Enterprise capability. Contact us to enable it for your organization. The default Pro plan instead uploads a client-side encrypted comparison (oasdiff stores only ciphertext it cannot read), see Setting up oasdiff Pro.

For GitHub org admins

oasdiff Pro needs two GitHub integrations: the OAuth app, so signed-in members can view breaking-change reports on oasdiff.com, and the GitHub App (oasdiff[bot]), which posts the breaking-change comment on the pull request itself. They're independent approval flows — order doesn't matter — and the sections below cover each.

1. OAuth app approval (lets oasdiff read your org's private repos for signed-in members)

Needed if your organization has restricted third-party OAuth applications. Sign-in itself still works without this approval (it's a personal GitHub action). What fails is reading your organization's private repositories on oasdiff's behalf: GitHub blocks the read even though the member has access. The review page surfaces a wall with a direct link to your authorization page so the member can request approval (or grant it themselves if they're an org owner).

Approving the OAuth app lets each signed-in member authorize their own personal GitHub access for oasdiff to read on their behalf. That access is scoped to whatever the member already has on GitHub, used only when they explicitly open a change review, and the spec contents oasdiff fetches are never stored on our side. The OAuth app itself has no standing server-side credential against your organization — oasdiff can only act in real time, while a member is signed in and looking at something. The information oasdiff requests is minimal:

To approve: go to your organization's OAuth application policy page. You'll see oasdiff either as a pending request (a member has tried to use it) or in the denied list (a prior request was declined). Click Approve. This is a one-time action per organization.

2. Install the oasdiff GitHub App on your repositories

Needed for the pull-request comment and the oasdiff / API changes status check on pull requests. The App posts as oasdiff[bot] (its own identity, not impersonating any user).

The App does not request access to code (Contents), issues, branches, actions, secrets, or any other resource. Code is never read by the App. OpenAPI spec files are fetched separately using each reviewing user's own OAuth token, so spec access strictly follows that user's GitHub permissions.

To install: visit github.com/apps/oasdiff/installations/new, select your organization, and choose either All repositories or a specific list. You can change the list later from the App's configuration page.

3. Grant repo access to your users

oasdiff never reads repo content with its own credentials, only with the reviewing user's OAuth token. Each user who needs to review a private repo must have read access to it (org member with role-based access, team membership, or outside collaborator). A user who isn't a collaborator will see an "Access denied" wall on oasdiff.

4. (Optional but recommended) Branch protection

For Pro's "block merge until reviewed" feature, add oasdiff / API changes to the required status checks on your protected branches. Without this, the commit status is informational only and won't prevent merging.

Email your admin

Open a pre-filled message in your email client, then add the admin's address and send. If you've typed your org slug above, it's already substituted into the body and subject.

Subject: Approve oasdiff for {ORG} on GitHub

Hi,

I'd like to use oasdiff (https://oasdiff.com) on our APIs. It detects breaking changes in OpenAPI specs and surfaces them on pull requests so we catch them before they ship.

Because {ORG} enforces SAML SSO and/or OAuth-app approval on GitHub, I need your help with two one-time approvals:

1. Approve the oasdiff OAuth app for {ORG}
   Go to https://github.com/organizations/{ORG}/settings/oauth_application_policy
   Find "oasdiff" in the pending requests list and click Approve.

2. (For the pull-request comment feature) Install the oasdiff GitHub App on the repos we want covered
   Go to https://github.com/apps/oasdiff/installations/new
   Select {ORG} and choose either "All repositories" or specific repos.

oasdiff publishes the full list of permissions it asks for and what each one is used for here:
https://oasdiff.com/docs/enterprise

Happy to forward you the security overview or jump on a quick call if you'd like more detail.

Thanks!

Add the CI workflow to your repository

With the GitHub App installed and the OAuth app approved, the last setup step is wiring the Action into your repository's CI. The Action runs on every pull request, posts a formatted PR comment listing each breaking change, and sets the oasdiff / API changes commit-status check on the PR head.

The dashboard's "Add to repo" flow does this for you automatically (it opens a PR with the workflow file and stores the secret). If you'd rather wire it up by hand, the workflow looks like this:

name: oasdiff
on:
  pull_request:
    branches: [ "main" ]
jobs:
  pr-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - run: git fetch --depth=1 origin ${{ github.base_ref }}

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

Replace openapi.yaml with the path to your OpenAPI spec file. The OASDIFF_TOKEN repository secret holds your tenant ID, find it on your dashboard and add it under Settings → Secrets and variables → Actions.

The PR comment links to a review page where your team can approve or reject each breaking change. Approvals carry forward automatically, if the same breaking change appears in a later commit, it stays approved. The commit-status check stays pending until all breaking changes have been reviewed, then flips to success. Pair it with a branch protection rule (admin step 4 above) to enforce sign-off before merge.

Four organization-side states for the OAuth app

On your organization's OAuth application policy page, oasdiff can sit in one of four states. Which one your organization is in determines whether reviews work and what the recovery is:

Troubleshooting: what each error message means

If you opened a review URL and saw an error message instead of the side-by-side diff, find the heading you saw in the table below:

What oasdiff stores, transmits, and never sees

• OpenAPI spec content is transient. Specs are fetched on demand to compute the diff and render the review page, and discarded immediately. They are never persisted to the oasdiff database.
• Reviewer OAuth tokens are session-only. Stored in an HTTP-only cookie on the reviewer's browser. Never written to the oasdiff database.
• GitHub App installation tokens are short-lived and in-memory only. Cached per repository for at most one hour; never persisted to disk or database.
• The GitHub App is used only for writes oasdiff performs under its own identity (PR comments, commit statuses). It is never used to read repository contents on behalf of a user.
• What is stored: the signed-in user's GitHub username, email, and avatar URL; the repository owner, name, and pull-request number for each report; the per-change review decisions and the reviewer's GitHub username; subscription state.

For the full data inventory and legal basis, see the privacy policy.

Common questions

Do I have to start a Pro trial to use oasdiff?

No. Signing in at oasdiff.com/register does not start a trial. If you only want to view a free change review someone shared with you, that's the right URL, sign in and head back to the review. The Pro trial only activates when you specifically visit oasdiff.com/start-trial or click Start free Pro trial on your dashboard. The CLI and the free GitHub Action don't require any oasdiff account at all.

Does approving the OAuth app give oasdiff access to our code?

No. Approving the OAuth app only allows individual members of your organization to sign in to oasdiff.com and authorize their own GitHub token for the org. Each user's access is whatever their personal GitHub account already grants them. The OAuth app itself has no standing server-side credential against your organization.

Does installing the GitHub App give oasdiff access to our code?

No. The App requests only Pull requests: read & write and Commit statuses: read & write. It does not request the Contents permission, which is the one that would grant repository code access.

Can we limit the GitHub App to a few repositories first?

Yes. At install time, choose Only select repositories and pick the ones you want covered. You can add or remove repositories at any time from the App's configuration page on github.com.

Can we revoke approval later?

Yes, both. The OAuth app approval can be revoked from the same oauth_application_policy page. The GitHub App can be uninstalled from the organization settings under Installed GitHub Apps. Revocation takes effect immediately.

We use the CLI and the free GitHub Action only. Do we need to approve anything?

No GitHub-side approval is needed to run the CLI or the free GitHub Action. The CLI runs entirely on the user's machine. The free Action runs inside your own CI and uses your repository's built-in GITHUB_TOKEN, not any oasdiff-owned credential. The approvals on this page are only needed for the oasdiff.com review surface and for the Pro pull-request comment.

Next steps

Get help

Email info@oasdiff.com with any setup, security, or procurement questions. We can also walk through the approval steps with your IT or Security team on a short call.