GitHub Cloud setup

Git host permission requirements

In order to use all integration services which include repo, pull request, ticket and webhooks, the service account owner needs to be an owner on the GitHub organization.

OAuth permissions

Flow only requires read access to your repositories. This permission is needed to process the metadata used to generate our reports. GitHub does not offer the ability to narrow permissions down to just read-only access to private profile information and repositories. GitHub's standard OAuth permissions include write plus full admin permissions, which are never used by our system. These access levels are required in order to use GitHub APIs. 

Access token permissions

In addition to the minimum access token scopes, the service account holder needs to be an owner on the GitHub organization in order to utilize all integration services and webhooks.

If the service account holder is only a member of the organization, all services except webhooks will be available in Flow.

Webhook permissions

In order to enable webhooks, the service account needs to be a GitHub organization owner and at least one repo needs to be imported from the organization.

back to top

Connect via OAuth

Connecting via OAuth is the fastest and easiest way to connect your repos and import your data, including pull requests and tickets.

1. Click Settings on Flow's top navigation.
2. On the left navigation under Integrations, click Integrations.
3. Click Add Integration in the top right hand corner of the Integrations page.
4. Click GitHub on the Integration Provider list.
5. Under the OAuth tab, click Connect to GitHub.
6. If you're already logged into your GitHub account, a pop-up will appear prompting you to confirm access.

Once you've successfully connected, proceed to the Finishing up section of this article to complete the integration process.

back to top

Connect via access token

To connect via an access token, please use the Access token authentication method outlined in this GitHub Help Center article (external site, opens in new tab).

Now that you've generated a new token, these are the scopes Flow needs in order to import and process your repos and projects and to enable webhooks:

• repo (all)
• admin:org
  • read:org
• admin:repo_hook (all)
• admin:org_hook
• user
  • read:user

Once you've created your token, copy and paste it into the Personal Access Token box on the Access Token tab of the GitHub integration screen in Flow and click Test connection.

If the connection was successful you'll see the following message: Successfully connected via username.

back to top

Finishing up

Once you have a successful connection, finalize your integration and begin importing repos.

1. Click Next.
2. Select the services you want turned on for this integration. If you would like Flow to ingest ticket data and pull request data in addition to repo data, then leave all three services on. You can turn services on and off at any time.

   

3. Click Next.
4. Name your integration so you can identify the account you connected with.

   

5. Click Create.

Next, make sure your data is processing correctly. If you're not already on the Integration details page for your new GitHub integration:

1. Click Settings in the top navigation.
2. In the left navigation, click Integrations.
3. Click the integration you just created.
4. Click the Repos tab.

Make sure all the expected groups and projects appear in the Repos tab.

Begin importing repos by clicking the repo import page.

To learn more about managing your new integration settings, see Managing integrations.

back to top

Troubleshooting

If you’re unable to see your GitHub group in the Repo tab after you’ve successfully connected by account, there are two likely reasons:

• Permissions: If you're a member of the organization, send a request to the owner of the organization to grant permissions to Flow.
• Organization access: Organization access may not have been granted during the setup of your GitHub integration. If private repos are missing, ensure the service account has been granted access to each private repo you want to see in Flow.

To provide permissions:

1. In GitHub, under Settings, click Applications. Click Authorized OAuth Apps. Next, click on the Flow application.

   

2. Here, you can see which organizations Flow has access to. As seen below, Flow does not have access to the myorgsname organization.

   

   Note: If you're a member of the organization and not the owner, click the Request button next to your organization name. An owner of the organization will receive your request and will be able to grant or deny it. If you don’t see a Grant or Request button, see the section below.

To give Flow organization access:

1. Click the Grant button next to the organization’s name. If you don't see a red x next to the organization, you need to grant permissions at the organization level in GitHub, as shown below.

   

2. Under your GitHub Settings, click the organization you want to give Flow access to.

   

3. Under the organization’s settings, click Third-party access and click the edit button next to the Flow application.

   

4. Click Grant access. This gives Flow access to your GitHub organization.

   

Now that you've granted Flow access, return to Flow. Under your GitHub integration, select the Repos tab and check to make sure that groups are showing as expected. If you don't see all your GitHub organizations you may need to refresh the page.