Important: We strongly recommend you use a service account to create this integration. Please see How to Create a Service Account for instructions to create a service account, and read more about why service accounts are recommended here.
In this article:
- Git host permission requirements
- Connect via OAuth
- Connect via username and password
- Connect via access token
- Finishing up
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 will need to be an owner on the GitHub organization in order to utilize all integration services (repos, PRs, tickets) and webhooks.
If the service account holder is only a member of the organization, all services (repos, PRs, tickets) 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.
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: Starting on your Flow home page, go to the top navigation bar and click Settings. On the left navigation under Integrations, click Integrations.
2: Select the Add Integration button in the top right hand corner of your integrations screen.
3: Select GitHub from the Integration Provider list.
4: Under the OAuth tab, click Connect to GitHub.
5: If you are already logged into your GitHub account a pop-up will appear prompting you to confirm access.
Note: If you are not already logged in, you will be prompted to log in and then authorize the connection.
6: Once you have successfully connected, you may proceed to the Finishing up section of this document to complete the integration process.
Connect via username and password
To connect via your GitHub username and password, use the Username/Password authentication method.
Note: GitHub will be deprecating basic authentication in November, 2020. We suggest using an alternative authentication method at this time.
1: Input your username and password then click Test connection.
2: If the connection was successful you will see the following message: Successfully connected via "username"
Two factor authentication
At this time, two factor authentication is not supported via username and password. If your account has two-factor authentication enabled, you will need to use OAuth or a personal access token.
You will see the following message if you try and connect via username and password when you have two factor authentication enabled: Two-factor authentication is enabled. Please use a personal access token or app password to continue.
Connect via access token
To connect via an access token, please use the Access token authentication method outlined in this GitHub Help Center article.
Now that you've generated a new token, these are the scopes Flow needs in order import and process your repos and projects and to enable webhooks.
Once you have created your token, copy and paste it into your GitHub integration in Flow and click Test connection.
If the connection was successful you will see the following message: Successfully connected via "username"
Once you have a successful connection you can finalize your integration and begin importing repos.
1: Click Next
2: Next, 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. Click Next.
3: Name your integration so you can identify the account you connected with. Click Create
4: You have successfully created a new GitHub cloud integration.
5: If you see all the appropriate groups/projects under the Repos tab -on the integrations page, that indicates that Flow has the correct access to any repos associated with these groups/projects.
You can begin importing repos by clicking the repo import page.
To learn more about managing your new integration settings, see Managing integrations.
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 are a member of the organization, you will need to 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.
You can remedy either scenario by following the steps below:
1: In GitHub, under Settings, click Applications then Authorized OAuth Apps, then click on the Flow application.
2: Here, you will be able to see which organizations Flow has access to. As seen below, Flow does not have access to the “myorgsname” organization.
Note: If you are 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.
3: To give Flow access to the organization, click the Grant button next to the organization’s name.
If you don't see a red “x” next to your organization, rather than the Grant button, you will need to grant permissions at the organization level in GitHub, as shown below.
Under your GitHub Settings click on the organization you want to give Flow access to:
Under the organization’s settings click Third-party access and click the edit button next to the Flow application.
Click the Grant Access button. This gives Flow access to your GitHub organization.
4: Now that you have granted Flow access, head back over to Flow. Under your GitHub integration, select the Repos tab. If you do not see all your GitHub organizations you may need to refresh your webpage.
If you need help, please email firstname.lastname@example.org for 24/7 assistance.