GitHub Enterprise Server setup

This is a step-by-step guide for connecting your GitHub Enterprise Server (self-hosted) account to Flow. If your repositories are behind a firewall, please allowlist our IPs on port 443 over HTTPS. You also need a public DNS record pointing to the IP address that is being exposed for Flow analysis. This DNS entry should match the TLS/SSL certificate the server is utilizing.

Use a service account to create this integration. Learn more about creating a service account.

Permission requirements

In order to utilize all integration services—including pull requests, tickets, and webhooks—the service account needs to be an owner on the GitHub organization.

If the service account is only a member of the organization, webhooks will not be available in Flow. All other services such as repos, PRs, and tickets will be available.

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.

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. Learn more about webhooks.

GitHub app permissions

You must have a user with permission to install the GitHub app (external site) on all organizations you want Flow to ingest data from.

If you're integrating with GitHub Enterprise Server, you must have a user with permission to register a new GitHub app (external site).

When finishing the integration in Flow, you must have a user with permission to view GitHub app installations on organizations you want to ingest data from who is also a member of those organizations. We recommend using the same user credentials of the user who installed the GitHub app on your organizations. This user will authenticate via OAuth.

The credentials of the user in Flow are only used at the moment of finalizing the integration and aren't used again later. If the user who created the integration leaves your organization, the integration with Flow won't be impacted as long as the app is still installed on your organizations. Trying to create multiple GitHub app integrations using the same OAuth credentials to retrieve organizations may result in errors. If you experience errors, wait 24 hours to try again.

OAuth permissions

Flow only requires read access to your repositories. Flow needs this permission 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. When connecting to GitHub, their standard OAuth permissions include write and full admin permissions. These permissions are never used by our system. These access levels are required in order to utilize GitHub APIs.

Create your integration

There are three ways you can connect to your GitHub Enterprise Server account:

GitHub App requires you to register a new GitHub app and install it on your organizations.
OAuth requires you to create an OAuth application in your GitHub Enterprise Server account.
Access Token requires you to create an access token in your GitHub Enterprise Server account.

To connect your GitHub Enterprise Server, first create a new integration.

In the top navigation, click Settings.
In the left navigation under Integrations, click Integrations.
Click Add Integration in the top right corner of the Integrations page.
Select GitHub Enterprise Server (Self-hosted) from the Integration Provider list and click Next.
Choose one of the three ways to connect your GitHub Enterprise Server account.

GitHub App

Self-hosted GitHub doesn't have access to the public GitHub marketplace. You must register a new GitHub app (external site) within our Enterprise Server instance, which Flow will use to ingest data.

Use the following information to register the app.

Any setting not mentioned here can be left as the default setting.

App Name: Flow
Description: Add anything to help you identify the app later.
Homepage URL: https://appfire.com/flow
Callback URL: https://<workspace>.appfireflow.com/accounts/complete/github-enterprise-app
Permissions: Read-only
- Repository Permissions
  - Administration
  - Contents
  - Deployments
  - Discussions
  - Issues
  - Metadata
  - Pull Requests
- Organization Permissions
  - Members
- Account Permissions
  - Email addresses
Make sure these are unchecked:
- Webhook Active
- Request user authorization (OAuth) during installation
- Enable device flow

Once the new GitHub app for Flow is registered:

Copy the Client ID, Client secret, App ID, and Private key. You'll need this information to finish your integration in Flow.
Install the GitHub app (external site) on each GitHub organization you want Flow to ingest data from.

After integrations are created, GitHub app-based integrations in Flow will behave the same as other integrations. However, you can't import teams from GitHub using integrations created with the GitHub app authentication method. Unlike OAuth or Personal access token-based authentication, both of which are tied to a specific user's permissions, GitHub app authentication does not rely on the same permissions structure. GitHub apps do not have any team management scopes, which are a requirement for importing teams from GitHub.

In Flow, navigate to Settings.
On the Integrations page, click Add integration.
Click the GitHub Cloud tile.
Select GitHub app - Flow as your authentication method.
Click the GitHub Enterprise Server (Self-hosted) tile.
Retrieve your organizations
- If you've already created an integration with the GitHub app authentication method and want to use the same app, click Select pre-existing app, then choose your app. Click Retrieve organizations via OAuth. In the pop-up modal, log in to the service account with the correct permissions. If asked, click Authorize for the app.
  —or—
- If you've never created an integration in Flow with the GitHub app authentication method or want to use a different app, click Create new GitHub app in Flow.
  1. Insert the following information:
    - GitHub app ID: Found in your GitHub app.
    - GitHub App name: We recommend using the same name you did when registering the GitHub app. Whatever name you choose, make it identifiable for future use.
    - Base URL: The base URL of your GitHub Enterprise Server instance, excluding the trailing slash.
    - Client ID: Found in your GitHub app.
    - Client secret: Found in your GitHub app.
    - Private key: Found in your GitHub app.
  2. Click Retrieve organizations via OAuth. In the pop-up modal, sign in to the service account with the correct permissions. If asked, click Authorize for the app.
Click Next.
Select organizations
- This list only includes organizations with the Flow GitHub app installed that the service account has permission to view.
- Any organizations that have already connected to Flow will be grayed out. Organizations can only be associated with one integration in Flow.
  If an organization is missing from this 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.
Click Next.
Enable services for the integration.
Confirm your organization selections. Remember that each selected organization will be associated with its own integration in Flow.
Click Done.

Once you finish creating your integration, Flow creates a separate integration for each organization you selected, with the name of the integration the same as the name of the organization. Each integration and its repos are managed separately in Flow.

OAuth

Connecting via OAuth requires you to first create a new OAuth application (external site) in your GitHub Enterprise account.

Create the OAuth application using the following information:
- Name: Flow
- Homepage URL: https://appfire.com/flow
- Description: Authorizing with your Flow account allows Flow to conveniently display your repos to make importing them efficient. You will get to pick which repos to import. Flow won't access any of your other repos.
- Callback URL: https://<workspace>.appfireflow.com/accounts/complete/github-enterprise/
Navigate back to the OAuth Apps page in your GitHub account. Gather the Client ID, Client Secret, and Base URL.
Paste this information into the authorization page in Flow. Make sure you are not blocking pop-ups, as you will need to authorize the application.
Click Connect to GitHub Enterprise Server (Self-hosted).

If your connection was successful, you will see a success message.

If you are not able to connect to your account, check your Client ID and Client Secret to make sure they are correct and try again.

Access token

To connect via an access token, use the Access token authentication method. Create an access token in GitHub Enterprise Server (external site).

In the Select Scopes section, select the scopes below. Flow needs these scopes 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 have created your token, copy and paste it into your GitHub Enterprise Server integration in Flow and click Test connection.

If the connection was successful you will see a success message.

Full Agent Connection

You can also integrate GitHub with Flow via the Flow Agent by selecting the Full Agent Connection as the connection method.

Finishing up for OAuth and Access token integrations

Once you have successfully connected to your GitHub Enterprise Server account, click Next.
On the next screen, select the services you want turned on for this integration. If you want to import ticket and pull request data in addition to repo data, then leave all services on. You can turn services on and off at any time. Click Next.
Name your integration so you can identify the account you connected with. Click Create.
You have successfully created a new GitHub Enterprise Server integration.
To learn more about managing your new integration settings, see Manage integrations.

If you're using the GitHub app, manage your integrations in Flow as usual. However, once an integration is created through the GitHub app authentication method, it can't be edited to use a different authentication method. If you need to switch authentication methods, create a new integration with the new method, then delete all GitHub app-based integrations.

Edit the Client ID, GitHub app name, Base URL, and Private key if they change in your system. To do this, on the Integrations page, click Edit GitHub apps. Every time you update any of these fields, you must re-enter the Private key to save the changes. Changing these fields for a GitHub app in Flow will automatically update all integrations created using that GitHub app.

Troubleshooting

Connection test error

If you receive an error message when testing your connection during the setup process, check the following:

If we are unable to connect to your URL.
1. Verify that Flow IP addresses are allowlisted if you are behind a firewall.
2. Ensure your domain is accessible outside your network via public DNS resolution. If your public domain is different from your internal domain, you will need a reverse proxy in place in order for Flow to be able to import and process your data.
3. Make sure you're using a valid SSL certificate signed by a public CA.
If the authorization failed, check your credentials and try again.

If you are unable to see specific repos after data is ingested, ensure all permissions for the service account have been correctly set up. Also, make sure the service account has been added directly to any private repos you want to ingest data from.

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.