Connect to GitHub Enterprise

The steps below will guide you through the configuration needed to include files from a GitHub Enterprise instance.

You can add data from one or several GitHub Enterprise instances. For each instance, follow the instructions below.

Requirements

To include data from GitHub Enterprise, it must fulfill these requirements:

1. It must be reachable via a public DNS entry and IP.

2. It must use HTTPS.

3. The HTTPS certificate must be valid. Self signed certificates or certificates signed by your own root certificate authority are not accepted.

4. The firewall has to allow traffic from the public internet. Or you can choose to use a static IP, so you can white list the IPs in the firewall. The Static IPs are 3.251.32.127, 54.195.145.1. When using the static IP, QuotaGuard is used with its privacy and security policy.

Connect to GitHub Enterprise from AWS IP

When GitHub Enterprise content is included in Confluence, Include GitHub will try to connect from the outside to your network. It will find the IP via public DNS and tries to connect to your GitHub instance. Therefore your firewall must allow traffic from the outside.

Connect to GitHub Enterprise from dedicated Static IP

The 'Static IP` option will ensure that Include GitHub connects the specified IPs, so that your firewall can limit incoming traffic to those IPs. The Static IPs are 3.251.32.127 and 54.195.145.1. When using the static IP option, QuotaGuard is used with its privacy and security policy. GitHub still must have a public IP and a public DNS entry.

Please ensure your firewall allows incoming HTTPS traffic from these IPs on the following ports:

• 443 (standard HTTPS)

• 8443 (alternative HTTPS)

Configuration Steps

You can use one of two authentication method to access resources from a GitHub Enterprise instance: Personal OAuth Authentication or Shared Access Token.

Personal OAuth Authentication

Every Confluence user needs to authenticate via OAuth to this GitHub site in order to access included private repository files. OAuth authentication with GitHub Enterprise and a GitHub account for each user is required. Users can only access files they can view on GitHub Enterprise.

Step 1: Get configuration information for the app in Confluence

Within Confluence, navigate to the app configuration panel (Confluence administration → Apps → Include from GitHub to Confluence → GitHub Enterprise → Add+ → Personal OAuth for each Confluence user) to obtain the configuration information needed to register the app in GitHub. A configuration guide will be provided in this panel.

Step 2: Register the app as an OAuth app in GitHub

You need to register the app as an OAuth app in GitHub:

1. Navigate to the organization where Include GitHub for Confluence should be registered.

2. Navigate to the organisation settings to register a new OAuth app (Found under Settings →  Developer Settings → OAuth Apps).

3. Enter the information obtained from the Include from GitHub to Confluence app settings in Step 1

   

4. Complete the registration and create a client secret.

   

5. Copy the client id and client secret that will be used for the app config in Confluence.

Step 3: Add the GitHub credentials in the app configuration panel

Within the app config panel from step 1, add the GitHub instance url, client id and client secret obtained in step 2.

Step 4: Access GitHub content through the macro

You will now be able to add files from your GitHub instance through the macro. Users will simply need to authenticate with the GitHub instance (so that user can only view files for repos that they have permissions for).

The file will be rendered for the user if he has the relevant permission to access it.

Shared Access Token

All Confluence users access this site with this configured access token. They do not need any account on GitHub. They see included files which the token has access to.

1. Create the Access Token

1. Log into GitHub: On GitHub Enterprise, navigate to User (click on Avatar) → Settings → Developer Settings → Personal access tokens → Fine-grained tokens

2. Generate a new fine-grained token

   1. Select the Resource owner:

      • Choose your personal account or

      • Choose your organization (available if the organization allows fine-grained tokens)

   2. Select the repositories you want to grant access to

   3. Use the following permissions:

      • Contents: Read-only

      • Pull requests: Read-only

      • Issues: Read-only

   4. Set an expiration date

2. Add the GitHub access token to configuration panel

Add the created access panel to the app configuration: