Skip to main content

Connect to GitHub

Connect GitHub to Retool and manage repositories, issues, pull requests, and workflows.

GitHub is a platform for hosting and collaborating on Git repositories.

What you can do with GitHub in Retool​

After you create a GitHub resource in Retool, you can:

  • Retrieve repositories, issues, pull requests, and workflow runs.
  • Create and update issues and pull requests.
  • Manage repository collaborators, labels, and branches.
  • Automate repository and issue management from other systems.

Before you begin​

To connect GitHub to Retool, you need the following:

  • Authentication credentials: A personal access token, or an OAuth App if you prefer OAuth.
  • GitHub permissions: User account with appropriate permissions to access and manage the data you need.
  • Retool permissions: Ability to create and manage resources in your organization.

Create a GitHub resource​

Follow these steps to create a GitHub resource in Retool.

Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for GitHub and click the GitHub tile to begin configuration.

GitHub resource configuration form.

Configure general settings​

Specify a name and description for the resource that indicates which GitHub account or organization it connects to. The description provides more context to users and Assist about how to use the resource.

Example nameExample description
GitHub (Engineering)Personal access token used to manage the engineering team's repositories.
GitHub (Release automation)OAuth connection used to automate release issue tracking.

API version​

Select the GitHub API version to use. Retool defaults to the most recent version, but you can select the legacy version if your integration depends on it.

Example
v1.1.4 (DEFAULT)

Configure authentication​

GitHub supports authenticating with a personal token or with OAuth 2.0.

Authentication methodUse cases
Personal TokenQuick setup for a single GitHub account. No OAuth App required in GitHub.
OAuthEach user authenticates with their own GitHub account, or credentials are shared across all users of the resource. Requires a GitHub OAuth App on both Cloud and self-hosted, since GitHub doesn't support Retool's hosted OAuth app.
Option A: Personal Token (Recommended)
  1. Select Personal Token from the Authentication dropdown.
  2. Generate a token from GitHub's personal access tokens settings.
  3. Paste your GitHub username into the GitHub username field.
  4. Paste the token into the GitHub personal token field.
Example
GitHub username: octocat
GitHub personal token: ghp_1234567890abcdefghijklmnopqrstuvwxyz
Option B: OAuth

GitHub doesn't support Retool's hosted OAuth app, so both Cloud and self-hosted organizations must create a custom OAuth App in GitHub. Follow these steps, in order:

Create an OAuth App in GitHub​

Follow GitHub's guide to create an OAuth App. Note the Client ID and Client secret GitHub generates for the app.

Configure the resource in Retool​

  1. Select OAuth from the Authentication dropdown.
  2. Under Scopes, select the permissions Retool needs, such as reading or writing repository data.
  3. Copy the OAuth callback URL Retool displays and add it to the OAuth App's authorization callback URL settings in GitHub.
  4. Client ID: Paste the Client ID from GitHub.
  5. Client secret: Paste the Client secret from GitHub.
  6. Save the resource.
  7. Click Connect with OAuth and grant permissions in GitHub. Retool redirects you back once authorization completes.

Configure advanced options​

Configure optional settings available under the Advanced options section of the resource configuration form.

Outbound region​

If your organization uses outbound regions, select the region that should be used for requests to GitHub. This controls which geographic region your requests originate from.

Test the connection​

  • Personal Token: Click Test connection to verify Retool can connect to GitHub using your token.
  • OAuth: GitHub OAuth connections don't include a Test connection button. After you authorize the connection, Retool displays a Connected status once authentication succeeds.

Save the resource​

Click Create resource to save your GitHub resource. You can now use it in queries across your Retool apps and automations.

Interact with GitHub data​

Once you've created a GitHub resource, you can interact with GitHub data using Retool.

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

  • To use GitHub data in the app builder, reference the resource in the prompt with @, such as @GitHub (Engineering). Refer to the data and functions documentation to learn more.
  • For classic apps, workflows, and agents, refer to the GraphQL queries documentation to learn how to write a resource query.

Best practices​

Follow these best practices to maintain the security of your GitHub resource.

  • Use a personal token with least privilege: Personal tokens inherit the permissions of the GitHub account that created them. Select only the scopes the resource actually needs.
  • Rotate credentials regularly: Regenerate personal tokens and rotate OAuth client secrets on a regular schedule.
  • Avoid shared credentials for sensitive repositories: Enable Share credentials between users only when it's acceptable for all users of the resource to act as the same GitHub account. Otherwise, let each user authenticate individually.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate GitHub credentials for production, staging, and development.