> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth setup for GitHub

> Create a GitHub OAuth App, register it as a Foundry OAuth provider in Ravenna, and use it to read or write issues, pull requests, and repos from workflows.

Use this walkthrough to connect GitHub. Once connected, your functions can read or create issues, comment on pull requests, look up repositories, and more.

GitHub supports two kinds of apps: **OAuth Apps** (act on behalf of a user) and **GitHub Apps** (install on an org or repo with their own permissions). This walkthrough uses **OAuth Apps**, which match Foundry's "user signs in with their own account" model.

<Callout icon="link" color="#6B7280">
  New here? Start with the [OAuth setup overview](/guides/how-to/foundry/setup-oauth/overview) for the shape and prerequisites that apply to every provider.
</Callout>

***

## Before you begin

You'll need:

* **Organization admin** access in Ravenna.
* A GitHub account with permission to create an OAuth App in your organisation (Settings → Developer settings).
* An idea of which scopes your function will need. For example, `repo` to read or write private repos, `read:org` to read org membership, or `public_repo` for public-only access.

***

## 1. Create the OAuth App in GitHub

<Steps>
  <Step title="Open Developer settings">
    Go to your organisation (or personal) **Settings → Developer settings → OAuth Apps** and click **New OAuth App**.

    Creating it under the **organisation** is usually what you want, since the app then belongs to the org rather than to one person's account.
  </Step>

  <Step title="Fill in the basics">
    * **Application name**. For example, "Ravenna Foundry."
    * **Homepage URL**. Your Ravenna URL (e.g. `https://app.ravenna.ai`).
    * **Authorization callback URL**. Ravenna's OAuth callback:

      ```
      https://app.ravenna.ai/api/integrations/foundry-oauth/callback
      ```

      Replace `app.ravenna.ai` with your custom domain if you use one.

    Click **Register application**.
  </Step>

  <Step title="Generate a client secret">
    On the app page, click **Generate a new client secret** and copy it immediately. GitHub only shows it once. Also copy the **Client ID** shown at the top.
  </Step>
</Steps>

<Info>
  GitHub OAuth Apps don't have a per-app scope list. Scopes are requested at sign-in time, and you'll set them in Ravenna in the next section.
</Info>

***

## 2. Register the provider in Ravenna

<Steps>
  <Step title="Open Settings → OAuth Providers">
    In Ravenna, go to **Settings → OAuth Providers** and click **Add Provider**.
  </Step>

  <Step title="General tab">
    Fill in:

    * **Name**. For example, "GitHub."
    * **Slug**. `github`.
    * **Description** and **Logo**. Optional but helpful.
    * **Base URL**. `https://api.github.com`.
    * **Docs URL**. `https://docs.github.com/en/rest`.
  </Step>

  <Step title="OAuth tab">
    Fill in the details from GitHub:

    * **Authorization URL**. `https://github.com/login/oauth/authorize`
    * **Token URL**. `https://github.com/login/oauth/access_token`
    * **Scopes**. The GitHub scopes your function needs, space-separated. Common examples:
      * `repo` for full access to public and private repos.
      * `public_repo` for public-repo access only.
      * `read:org` to read org membership.
      * `workflow` to read and update GitHub Actions workflows.
    * **Client ID** and **Client secret**. Paste the values from GitHub.

    GitHub returns tokens as form-encoded by default. To get JSON, add this:

    * **Token exchange parameters**:
      ```json theme={"system"}
      { "accept": "application/json" }
      ```
  </Step>

  <Step title="Research and save">
    Foundry researches the docs URL. Once it finishes, the provider is enabled and shows up in **Settings → Integrations** under the **Custom** category.
  </Step>
</Steps>

***

## 3. Connect an account

Each user who runs a function connects their own GitHub account once:

1. Go to **Settings → Integrations**, find GitHub in the **Custom** category, and click **Connect**.
2. GitHub shows the consent screen listing the scopes you requested. Approve.
3. You're back in Ravenna with a connected account.

<Info>
  GitHub OAuth tokens don't expire by default, so users won't need to reconnect unless they explicitly revoke access from GitHub's [Authorized OAuth Apps](https://github.com/settings/applications) page.
</Info>

***

## 4. Build a function on top

Open **Foundry**, click **New Function**, and connect the GitHub provider in the function's **Integrations** tab. Pick which connected GitHub account the function should run as. Then describe what you want it to do:

* "Create a GitHub issue in `acme/backend` with the given title and body. Apply the `triage` label and return the issue URL."
* "List the open pull requests in `acme/frontend` assigned to me. Return the title, author, and URL for each."
* "Comment on a pull request given its URL and a body. Return the comment URL."

<Callout icon="link" color="#6B7280">
  Full build → test → refine → publish loop: [Building functions](/documentation/automate/foundry/actions).
</Callout>

***

## GitHub-specific gotchas

**You see "bad verification code" or "incorrect\_client\_credentials."** The client ID or secret was pasted wrong, usually a stray space. Re-copy from GitHub and try again.

**SSO-protected repos return 404 even though they exist.** The user connected the app but hasn't authorised it for the SSO org. Each user must visit [Authorized OAuth Apps](https://github.com/settings/applications), click your app, and authorise it for the org under **Organization access**.

**You need a scope you forgot.** Edit the provider in **Settings → OAuth Providers**, add the scope, save. Existing users will need to disconnect and reconnect to consent to the new scope; GitHub doesn't expand an existing token's scopes.