Skip to main content
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.
New here? Start with the OAuth setup overview for the shape and prerequisites that apply to every provider.

​
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

1

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.
2

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.
3

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.
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.

​
2. Register the provider in Ravenna

1

Open Settings → OAuth Providers

In Ravenna, go to Settings → OAuth Providers and click Add Provider.
2

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.
3

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: 
    { "accept": "application/json" }
4

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.

​
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.
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 page.

​
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.”
Full build → test → refine → publish loop: Building functions.

​
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, 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.
Last modified on June 4, 2026