GitHub
Overview
Pre-built tooling
Pre-built integrations
Access requirements
Pre-Requisites | Status | Comment |
---|---|---|
Paid dev account | ✅ Not required | Free GitHub account is sufficient for development. |
Paid test account | ✅ Not required | Free GitHub account is sufficient for testing. |
Partnership | ✅ Not required | |
App review | ✅ Not required | No review process for OAuth Apps. |
Security audit | ✅ Not required |
Setup guide
GitHub offers two types of integrations: OAuth Apps and GitHub Apps. This guide covers setting up an OAuth App, which is simpler for basic API access. For more advanced use cases with fine-grained permissions, consider using a GitHub App instead.
Create a GitHub account
- If you don’t already have a GitHub account, go to GitHub’s signup page and create one.
- Sign in to your GitHub account.
Register a new OAuth application
- Navigate to your GitHub account settings by clicking on your profile photo in the top-right corner and selecting Settings.
- In the left sidebar, click on Developer settings.
- Select OAuth Apps in the left sidebar.
- Click the New OAuth App button.
Note: If this is your first time creating an OAuth app, you’ll see a Register a new application button instead.
Configure your OAuth application
Fill in the required fields:
- Application name: Enter a name for your application. This will be shown to users during the authorization process.
- Homepage URL: Enter the full URL to your application’s homepage.
- Application description (optional): Provide a description of your application to help users understand what it does.
- Authorization callback URL: Enter
https://api.nango.dev/oauth/callback
This is the URL where GitHub will redirect users after they authorize your application.
Register the application
- Click the Register application button.
- Your OAuth application is now registered, and you’ll be taken to its settings page.
Generate a client secret
- On your OAuth App’s settings page, you’ll see your Client ID displayed at the top.
- Click the Generate a new client secret button.
- GitHub will generate a client secret for your application. Make sure to copy and store this securely, as you won’t be able to see it again.
Note: Treat your client secret like a password. Never share it publicly or include it in client-side code.
Configure your integration in Nango
When setting up your GitHub integration in Nango:
- Use your Client ID and Client Secret from the previous steps
- For the authorization URL, use:
https://github.com/login/oauth/authorize
- For the token URL, use:
https://github.com/login/oauth/access_token
- For the scope, select the appropriate permissions your application needs
Test the OAuth flow
- After configuring your integration in Nango, test the OAuth flow to ensure it works correctly.
- The authorization flow will redirect users to GitHub where they can approve access to their account.
- After approval, users will be redirected back to your application with an authorization code.
- This code will be exchanged for an access token that can be used to make API requests.
Next
Follow the Quickstart.
Useful links
- GitHub Developer Documentation
- GitHub REST API Documentation
- Creating an OAuth App
- Authorizing OAuth Apps
- OAuth Scopes for GitHub
- Differences between GitHub Apps and OAuth Apps
- Registering a GitHub App
- GitHub App Permissions
Common Scopes
For a complete list of available OAuth scopes, see the GitHub documentation on OAuth scopes.
API gotchas
- When setting up a GitHub App:
- The App ID is made of numbers (e.g. 401953)
- The App Public Link is the URL to your Github App public page (e.g. https://github.com/apps/nango-github-app)
- The App Private Key needs to be generated in your GitHub App settings and starts with
-----BEGIN RSA PRIVATE KEY-----
(not to be confused with the Client Secrets) - The Setup URL (displayed on your Nango integration page) needs to be added to your GitHub App configuration (not to be confused with the Callback URL that can stay empty)
- When setting up a GitHub App OAuth:
- The App ID is made of numbers (e.g. 401953)
- The App Public Link is the URL to your Github App public page (e.g. https://github.com/apps/nango-github-app)
- The App Private Key needs to be generated in your GitHub App settings and starts with
-----BEGIN RSA PRIVATE KEY-----
(not to be confused with the Client Secrets) - The “Callback URL” needs to be filled in with the callback URL which unless customized will be https://api.nango.dev/oauth/callback and the checkbox “Request user authorization (OAuth) during installation” should be checked
- The checkbox “Redirect on update” under “Post installation” should NOT be checked and the “Setup URL (optional)” should not be accessible
- There are certain API methods that only work with an OAuth App that will not work with an App. Please check the Github documentation and look for a “Works with Github Apps” header under the endpoint.
- The
github-app-oauth
is a combination of a Github App and OAuth and should be used when a Github App would need approval to be installed into an organization. - Nango supports initiating a connection with a GitHub App using the frontend SDK, but not directly from the GitHub Marketplace. Therefore, you should encourage users to install your GitHub App from your product, rather than from the GitHub Marketplace directly. This is a limitation we plan to fix in the future.