---
title: "GitHub Cloud setup"
canonical: "https://support.appfire.com/space/FD/1802535065/GitHub%20Cloud%20setup"
format: markdown
---
> Macro (aura-html)

Create a GitHub Cloud integration with Flow using OAuth or access tokens.

Flow retrieves commit, pull request, and ticket data from GitHub integrations.

> ℹ️ Ticket data from GitHub is only available in [Work log](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2894332489). Emoji reactions to pull requests do not count toward Flow metrics, but emojis added in the comment text field do.

> ⚠️ Use a service account to create this integration. Learn more about [creating a service account](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2892333437).

## Git host permission requirements

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.

> ℹ️ In addition to all permissions listed in this article, if you have any private repos, the service account must be added to each private repo for Flow to ingest data from them.

#### **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 limit permissions to read-only access to private profile information and repositories. GitHub's standard OAuth permissions include write and full admin permissions, which our system never uses. These access levels are required to use GitHub APIs. 

> ℹ️ When connecting GitHub Cloud to Flow via OAuth, the OAuth application must be [authorized (external site, opens in new tab)](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps) and [approved (external site, opens in new tab)](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization) in GitHub.

#### **Access token permissions**

In addition to the minimum access token scopes, the service account holder needs to be an owner on the GitHub organization 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**

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.

## Create your integration

To connect to GitHub Cloud;

1. Click **Settings** in Flow’s top navigation.
2. In the left navigation under Integrations, click **Integrations**.
3. Click **Add integration**.
4. On the Integration Provider list, click GitHub Cloud.
5. Select your authentication method:

### GitHub app

After selecting GitHub app - Flow as the authentication method:

1. Click **Retrieve organizations via OAuth**.
2. In the dialog modal, log in to the service account with the correct permissions. If asked, click **Authorize Flow**.
3. Click **Next**.
4. Select organizations
  - This list includes only organizations with the Flow GitHub app installed that the service account is authorized to view.
  - Any orgs that have already been connected to Flow will be grayed out. Organizations can only be associated with one integration in Flow. If an organization is missing from the list, it's likely that it either doesn't have the app installed on it yet or the service account doesn't have permission to see the organization.
5. Click **Next**.
6. Enable services for the integration.
7. Confirm your organization selections. Remember that each selected organization will be associated with its own integration in Flow.
8. Click **Done**.

Once you finish creating your integration, Flow creates a separate integration for each organization you selected, with each integration named after the organization. Each integration and its repos are managed separately in Flow. Ensure the expected repos appear in each integration. Learn more about <u>[managing repositories](https://help.pluralsight.com/hc/en-us/articles/24353458266900-Managing-repositories)</u> to ensure your data is imported as you expect.

### OAuth

After selecting OAuth as the authentication method:

1. Click **Connect to GitHub**.
2. If you’re not already logged in, you’ll be prompted to log in and authorize the connection.
3. If you’re already logged in, a dialog will appear prompting you to confirm access.
4. Once your connection is successful, click **Next**.

> ℹ️ Ensure pop-ups are allowed in your browser. If you’re having difficulties connecting, try to make the connection in an Incognito browser.

Proceed to the steps for finishing up to complete the integration setup.

### Personal access token

Before setting up a GitHub Cloud integration in Flow, [generate an access token (external site, opens in new tab)](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with the following scopes:

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

Copy the access token and return to Flow.

After selecting Personal access token as the authentication method:

1. Paste the token in the **Personal access token** field.
2. Click **Test connection**. If the connection was successful, you'll see the following message: Successfully connected via username.

If SSO is configured for your GitHub organization, you must [authorize the token in GitHub to proceed (external site, opens in new tab)](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). If you refresh your token and update it in Flow, you must reauthorize SSO for the token for Flow to correctly ingest your data.

Proceed to the steps for finishing up to complete the integration setup.

### Full Agent Connection

You can also integrate GitHub with Flow via the [Flow Agent](https://appfire.atlassian.net/wiki/pages/createpage.action?spaceKey=fd&title=Git%20metadata%20collector&linkCreation=true&fromPageId=1802535065) by selecting the **Full Agent Connection** as the connection method.

## Finishing up OAuth and Personal access token integrations

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**.

Once the integration setup is complete, you’ll land on the integration details page.<span style="color: #130f25"> Make sure all the expected groups and projects appear in the Repos tab of your integration details page. </span>

Learn more about [managing repositories](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2893283817) to begin importing repos. To learn more about managing your new integration settings, see [Managing integrations](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2892595630).

## Troubleshooting

### Missing GitHub group in the Repo tab

If you’re unable to see your GitHub group in the Repo tab after you’ve successfully connected with an 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.
  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.

### Missing GitHub projects

If you’re not seeing any projects after you’ve successfully connected with a personal token, run the following code to check whether your credentials are working as expected and your privacy levels are set correctly:

```
curl --location 'https://SERVERNAME/api/v3/user/repos?per_page=100' \
--header ‘Accept: application/vnd.github+json’ \
--header 'Authorization: ******'
```

> ℹ️ For any authentication method you have used, double-check visibility and privacy settings on the repos you expect to see in Flow. If the `default visibility = none` or the repos are marked `private`, then a Service account user must be added as a Contributor to each repo you want to ingest data from.