Authenticate With GitHub
Graphite is built on top of GitHub’s APIs, so you need to provide Graphite access to your GitHub resources to create, review, and merge PRs.
GitHub authentication methods
Currently, GitHub is the only git provider that Graphite integrates with. When setting up an account with Graphite, you’ll have two options to authenticate with GitHub:
-
Option 1: Install the Graphite App (a GitHub App) on your organization (recommended)
-
Option 2: Provide Graphite with a Personal Access Token
We no longer support OAuth as an authentication method. Users who previously authenticated with OAuth remain supported, but new signups must use GitHub App or PAT.
Option 1 - Install the Graphite GitHub App
When creating an account on Graphite, it’s strongly recommended that you install or request installation of Graphite’s GitHub App on your organization.
GitHub Apps are the officially recommended way to integrate with GitHub. Some benefits for installing Graphite’s GitHub App on your organization:
-
Access to GitHub webhooks, which provides Graphite with push-based updates for information like CI status, mergeability, and real-time push events within seconds.
-
Access to the Graphite Merge Queue. The Merge Queue is only available if our GitHub App is installed on the organization.
-
Avoid hitting secondary rate limits with the GitHub API. This means fewer API requests to keep your data up-to-date, leading to fewer API errors and lower latency.
-
Provides the most security for your organization, giving users more control over which repositories the app can access through fine-grained permissions and short-lived tokens.
Install the Graphite App on an organization
You can only install a Graphite App on an organization if you’re an organization owner. If you’re not an owner, you should request to install the Graphite App instead.
If you’re an organization owner, you can install the Graphite App on your chosen organization by following the Graphite onboarding flow, or directly from the GitHub marketplace.
See GitHub’s instructions to install an App from the GitHub marketplace.
Request to install the Graphite App on an organization
If you’re not an organization owner, you can request approval for the app to be installed. Once you’ve done so, you should reach out to an organization owner to have your request approved. You can find a list of organization roles and members using this link: https://github.com/orgs/{org-name}/people.
Authorize the GitHub App with your personal account
After the Graphite App has been installed on your organization or if you’re signing up for Graphite with an organization that has the app installed, you’ll also need to give the Graphite App approval to retrieve information about your GitHub account and make changes on your behalf.
The screen to do so will look like this:
Option 2 - Provide Graphite with a Personal Access Token
If you’re unable to authenticate/install the Graphite App for any reason, you can always use Graphite with a Personal Access Token. At any point in the Graphite onboarding flow, you can click “Authenticate with a personal access token”, and the screen will look like this:
From here, generate a token on GitHub with the requires scopes pre-selected and paste it into the field to continue account creation. Learn more about the scopes Graphite requires in our privacy and security docs.
Warning
GitHub Personal Access Tokens are designed to give command line tools limited access to work with your account. While they provide the minimum clearance to use the Graphite CLI and app, they give the user the added responsibility of granting the token the correct permissions and have a limited lifespan before they expire. You may have a slower/limited experience with Graphite if you proceed with a PAT.
Manage GitHub authentication
To make adjustments to your GitHub authentication and the resources which Graphite has access to, go to your GitHub authentication settings in Graphite: