---
title: Create a GitHub OAuth app for OpenConnector
description: Create a GitHub OAuth app, configure the callback URL, and connect
  GitHub to a self-hosted OOMOL OpenConnector runtime.
lang: en
canonical_url: https://oomol.com/en/docs/openconnector-github-oauth-app/
markdown_url: https://oomol.com/en/docs/openconnector-github-oauth-app.md
---

# Create a GitHub OAuth app for OpenConnector

Use a GitHub OAuth app when OpenConnector needs a user-authorized GitHub connection. GitHub also supports personal access tokens, but OAuth is better when you want an authorization flow instead of manually pasting a token.

## OpenConnector service

| Service ID | Provider | Auth type |
| --- | --- | --- |
| `github` | GitHub | OAuth2 |

OpenConnector's GitHub OAuth provider can request scopes such as `read:user`, `user:email`, `repo`, `workflow`, and `delete_repo`. Grant only the scopes you need for the actions you plan to run.

## Prerequisites

- A running OpenConnector runtime.
- A GitHub account or organization where you can create OAuth apps.
- The OpenConnector origin users open in the browser, such as `http://localhost:3000` or `https://connect.example.com`.

## Step 1: Set the OpenConnector callback URL

Build the callback URL by appending `/oauth/callback` to your OpenConnector origin. For local testing, use `http://localhost:3000/oauth/callback`. For a public deployment, set `OOMOL_CONNECT_ORIGIN`, restart OpenConnector, and use the public callback URL, such as `https://connect.example.com/oauth/callback`.

## Step 2: Register a GitHub OAuth app

In GitHub:

1. Open **Settings**.
2. Open **Developer settings**.
3. Open **OAuth Apps**.
4. Choose **New OAuth App**.
5. Fill in the app name and homepage URL.
6. Set **Authorization callback URL** to the exact OpenConnector callback URL.
7. Register the app.

GitHub's official guide is [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). GitHub OAuth apps have one authorization callback URL, so create separate apps for local, staging, and production if each environment has a different callback URL.

## Step 3: Copy the client credentials

From the GitHub OAuth app page, copy:

| GitHub value | OpenConnector field |
| --- | --- |
| Client ID | `clientId` |
| Client secret | `clientSecret` |

## Step 4: Save the GitHub client in OpenConnector

Use the OpenConnector web console:

1. Open the OpenConnector web console, such as `http://localhost:3000`.
2. Open **Providers** and select **GitHub**.
3. Choose **Configure OAuth Client** or **Edit OAuth Client**.
4. Paste the GitHub client ID and client secret.
5. Choose **Save OAuth Client**.

## Step 5: Connect and test

After saving the OAuth client, choose **Connect** on the GitHub provider page. Approve the GitHub OAuth app, return to OpenConnector, and confirm that the provider page shows the account as connected.

Use `github.get_current_user` as a low-risk test action from the console action list.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| Redirect URI mismatch | GitHub's authorization callback URL must exactly match `<openconnector-origin>/oauth/callback`. |
| The wrong account authorized the app | Sign out of GitHub or use a clean browser profile before starting authorization. |
| Repo actions fail | The connection may not have `repo` scope or the user may not have access to the target repository. |
| Workflow actions fail | The connection may not have `workflow` scope. Reconnect after adjusting requested scopes. |
| Delete actions fail | Avoid `delete_repo` unless you intentionally need destructive repository actions. |