Onboarding troubleshooting


Authenticating Graphite as a GitHub App is the recommended method. However, if you don't have Organization owner permissions, you can try Graphite by authenticating using a Personal Access Token or through GitHub OAuth.

Having issues selecting an organization?

It may be unclear why some of your organizations do or do not appear during the Graphite onboarding flow.

First of all, you must have an organization. If you’re trying to use Graphite without an organization (for example, you’re a direct repository collaborator but not an organization member on the repository that you exclusively work on), we don't support this. The workaround is to choose your own personal organization.

Graphite can see your organizations to list them for selection only if:

  • The org doesn’t have OAuth restrictions enabled for the Graphite App (GitHub’s default is to enable OAuth restrictions, so this may not necessarily be the case for all organizations). An admin can manage OAuth App restrictions in {org-name} Settings > OAuth Application Policy.

  • Your membership in the organization is public (GitHub sets this to private by default). {org-name}'s home page > People

You can select one of these organizations and continue with the organization setup process as normal. If you don’t see your desired organization in this list and know that the Graphite GitHub App isn’t installed on your organization, you should click the Add organization from GitHub button. If you know that the Graphite GitHub App is installed on your org, you should click the Authenticate Graphite App button.

If you're still unable to select your desired organization, contact us at support@graphite.dev.

Don't see the repository you're looking for?

You can pick and choose which repositories within your organization you want the Graphite App to have access to. If you’re not seeing them in your repository selector, it's likely that you haven’t granted the Graphite App access to that repository. You can do so in the GitHub App settings within your org. (The URL will look like this: https://github.com/{orgname}/settings/installations)

If you're using a personal access token to onboard with Graphite and you don't see repositories for that organization, there are two possibilities:

  1. Your organization may use SAML SSO, so you must authorize the token after it's been created for it to have access to that organization's resources. See GitHub's instructions.

  2. The organization has restricted access to resources for classic PATs. See more about this on GitHub's documentation, and you can reach out to an organization owner to find out if they can lift this restriction.

Why is Graphite asking to act on my behalf?

You have arrived at this step because:

  1. The Graphite App is installed on your organization but you don’t see it in the organizations list

  2. You clicked Add organization from GitHub and the organization had the word Configure next to it in this list (indicating that the app is already installed on the organization)

This primarily treats the case where a new user is onboarding with Graphite and wants to join an organization that already has the Graphite App installed. Once you click this button, you will see a confirmation modal saying that we will redirect you to GitHub to authorize the Graphite App along with a special note that if you do so, the Graphite App will only have access to the organizations on which it's installed.

This button only appears if you haven’t already authenticated the Graphite App. Once you do so, you will return to the organization selection screen and see your desired organization.