Skip to main content

GitHub Setup

Configuring a custom GitHub OAuth App for use with Caddi

Caddi connects to GitHub through an OAuth App — GitHub's user-delegated app type, distinct from a GitHub App. Registration takes a couple of minutes and needs no GitHub review.

Create the app under your organization, not a personal account. Apps owned by an organization are automatically granted access to that organization's resources, which avoids a whole class of access problem. You can also transfer ownership later if you start in the wrong place.

Before you start

You'll need:

  • A GitHub account — GitHub Free is sufficient

  • Organization owner rights, if creating the app under an organization

  • Owner or Admin access to your Caddi organization

GitHub allows up to 100 OAuth Apps per user or organization.

Step 1: Register the OAuth App

A GitHub OAuth App has exactly one callback URL. Unlike GitHub Apps, you cannot add a second — any additional environment needs its own OAuth App registration.

  1. For an organization-owned app, go to your organization → Settings → Developer settings → OAuth apps, or directly to https://github.com/organizations/YOUR-ORG/settings/applications. For a user-owned app, use github.com/settings/developers.

  2. Click New OAuth App.

  3. Application name — Caddi

  4. Homepage URL — https://trycaddi.com

  5. Authorization callback URL — enter https://app.trycaddi.com/oauth-callback.

  6. Click Register application.

  7. Copy the Client ID.

  8. Click Generate a new client secret and copy it immediately — GitHub shows it once.

Step 2: Approve the app in each organization that needs it

This is the step that generates most GitHub support tickets. If a customer organization has OAuth app access restrictions enabled, Caddi gets no access to private repositories until an owner approves the app.

  1. In the organization, go to Settings → Third-party access (or Manage OAuth access).

  2. Find the Caddi app and approve it.

  3. Organization members can only *request* approval — an organization owner has to grant it.

Without approval, symptoms are subtle: private repositories look empty, privileged writes on public repositories fail, and no webhooks arrive from private repositories.

Step 3: Configure GitHub in Caddi

This step must be completed by a Caddi organization owner or admin.

  1. In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.

  2. Find GitHub in the list and click Configure.

Enter the following values:

  • Client ID — from your GitHub OAuth App

  • Client Secret — the value shown once when you generated it

Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.

Step 4: Connect your account

  1. Go back to the My Connections tab and find GitHub.

  2. Click Connect + and sign in to GitHub.

  3. Review the requested access and click Authorize.

  4. You'll be returned to Caddi with the connection active.

How the connection behaves

  • Scopes are requested at sign-in, not configured on the app. That's why there's no scope field here — it's correct by design, not an omission. Caddi requests repo read:org read:user user:email gist by default, which covers full read and write on public and private repositories without administrative reach.

  • repo is unavoidably broad for private repository access. GitHub OAuth Apps have no finer split — that granularity only exists in GitHub Apps.

  • Users can reduce the granted scope set, so a connection may come back with less access than requested.

  • Tokens do not expire by default and there is no refresh flow for OAuth Apps. Long-unused tokens may eventually be revoked by GitHub.

  • SAML SSO organizations need the token authorized separately for that organization.

  • Rate limits are 5,000 requests per hour per user for OAuth Apps, plus secondary limits on bursts.

  • Revoking access. Delete the OAuth App, revoke its approval in the organization, or have users revoke it from their GitHub authorized-apps list.

Troubleshooting

Private repositories appear empty

The organization has OAuth app access restrictions enabled and hasn't approved the app. An organization owner needs to approve it under Settings → Third-party access. This is by far the most common GitHub issue.

A callback URL error at sign-in

The single Authorization callback URL doesn't match https://app.trycaddi.com/oauth-callback. GitHub OAuth Apps allow only one, so correct it rather than adding another.

The client secret was lost

GitHub shows it once. Generate a new secret — this invalidates the old one — and update the configuration in Caddi.

Works for some repositories but not others in a SAML organization

The user's token needs SSO authorization for that organization. They can do this from their GitHub token settings.

Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.

Automation ideas

Law Firms

Legal review request → tracked issue

Caddi turns a contract or policy review request into a GitHub issue in your legal operations repository, with the document linked and the reviewer assigned.

Policy change merged → distribution

When a policy document merges, Caddi publishes the update to the firm and logs the version for compliance.

Related Articles
Did this answer your question?