Integrations & OAuth

Confirm your public URL

NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
BETTER_AUTH_URL=https://sim.yourdomain.com

Both must be your real public origin. If these are wrong, every OAuth round-trip fails with a redirect-URI mismatch.

Register an app with the provider

In the provider's developer console, create an OAuth 2.0 application. Register the redirect URI(s) for every Sim connector you want from that provider — one line per provider ID from the tables below.

For a Google app covering Gmail and Drive, for example, you register both:

https://sim.yourdomain.com/api/auth/oauth2/callback/google-email
https://sim.yourdomain.com/api/auth/oauth2/callback/google-drive

Scopes are requested by Sim at authorization time; you generally do not need to pre-declare them, but Google and Microsoft require you to enable the corresponding APIs on the project/app first (for example Gmail API, Drive API, Calendar API).

Set the credentials

Add the client ID and secret to the app's environment. In Kubernetes they go under app.env — the chart writes every key there into a chart-managed Secret — but supply the values through External Secrets or a pre-created Secret rather than committing them to a values file:

app:
  env:
    GOOGLE_CLIENT_ID: "..."
    GOOGLE_CLIENT_SECRET: "..."
    SLACK_CLIENT_ID: "..."
    SLACK_CLIENT_SECRET: "..."

Restart the app. Credentials are read at startup — a running pod will not pick up new ones.

Verify

Open a workflow, add the integration's block, and connect an account. A successful round-trip returns you to Sim with the account listed. A redirect-URI mismatch is the failure you will hit most; compare the registered URI against NEXT_PUBLIC_APP_URL character by character.

Register the App

For a team, open Your organizations → Settings for the organization that will own the App. For a personal App, open your account's Settings. Then choose Developer settings → GitHub Apps → New GitHub App.

Give the App a unique, recognizable name, such as Your Company Sim Search, and set Homepage URL to your Sim URL.

Under Identifying and authorizing users → Redirect URI (callback URL), enter:

<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/github-repositories

Replace <NEXT_PUBLIC_APP_URL> with your configured public origin, such as https://sim.example.com, without a trailing slash. The scheme, hostname, port, and path must match exactly; www and non-www hosts are different. See GitHub's callback matching rules.

Authorization starts from Sim so the callback can finish the pending connection. The Setup URL returns installation approval to that same setup attempt. Keep Request user authorization (OAuth) during installation disabled: Sim starts account authorization when it is needed, before installation. See GitHub's Setup URL guide.

For an existing deployment, deploy the application with the setup callback before changing the App registration. Use a separate GitHub App for each deployment origin, such as staging and production, so installation approval returns to the instance that started it. Keep the existing user authorization callback above unchanged.

The connector polls GitHub's API and does not need a webhook.

Set read permissions

Expand Permissions → Repository permissions. Set Contents → Access: Read-only; leave the mandatory Metadata permission at Read-only.

Expand Account permissions and set Email addresses → Access: Read-only.

Leave every other permission at No access. Sim does not need issue, pull-request, administration, or write permissions. GitHub's registration guide explains these settings.

GitHub App user tokens use these permissions rather than OAuth scopes. An empty scope value in the token response is expected; see GitHub's user token reference.

Set Where can this GitHub App be installed? → Any account to support connections from accounts outside the App owner. This lets any GitHub account install and authorize the App, subject to that account's organization policies. Making the App public does not make repositories public or grant anyone Search access. See GitHub's App visibility rules.

Select Create GitHub App.

Configure Sim

On the App's General settings page, copy its numeric App ID and Client ID, select Generate a new client secret, and generate a Private key. The App slug is the final part of its public URL: https://github.com/apps/<app-slug>.

Set all five variables using values from your GitHub App, then restart Sim:

GITHUB_APP_ID=<numeric App ID>
GITHUB_APP_SLUG=<app-slug>
GITHUB_APP_CLIENT_ID=<Client ID>
GITHUB_APP_CLIENT_SECRET=<Client secret>
GITHUB_APP_PRIVATE_KEY=<complete RSA PEM private key>

The private key must include its PEM header, footer, and contents. Sim accepts actual newlines or escaped \n sequences. When storing it in a JSON secret, use the plaintext JSON editor and encode each line break as \n inside the string. Single-line key/value fields can remove line breaks; replacing them with spaces makes the PEM invalid. Restart Sim after saving configuration changes.

Keep the private key and client secret in the deployment's server configuration; organization admins select installations in Sim without entering these secrets.

If you run Search indexing on Trigger.dev, configure the same five variables in its matching environment. The app server and indexing worker both need the App credentials; updating the app's secret store alone does not update a separately configured worker.

The Client ID is different from the numeric App ID. Use credentials from Developer settings → GitHub Apps. GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET belong to the separate GitHub sign-in integration and remain unchanged. Search does not read GITHUB_REPO_CLIENT_ID or GITHUB_REPO_CLIENT_SECRET.

Keep Expire user authorization tokens enabled so Sim receives the refresh token it needs to renew personal connections.

Complete the installation through the GitHub Search source setup.

If you replace a deployment's GitHub App, an organization admin selects Settings → Sources → More → Refresh connection settings. When Search is disabled, use Connected accounts → Providers → Update configurations in organization settings. This applies the deployment's current App configuration to all existing providers while preserving their option IDs. Accounts whose App configuration changed must reconnect. Then reconnect personal GitHub accounts and connect an installation of the new App. Reconnecting alone cannot update the organization's saved App configuration.