## Introduction

GitHub is a web based Git repository manager. This guide walks you through the steps to gather the necessary information and configure your GitHub organization for the purpose of creating an integration with Synqly's Identity connector.

## Prerequisites

Before you begin, ensure that you have:

- Access to the web interface of GitHub
- Access to a GitHub account that has a verified email address as well as admin permissions for the organization that the Synqly integration will be configured for


## Required Permissions

Due to restrictions on the Github REST API, a **Github Enterprise plan or server is required to use to the audit log functionality of the Synqly Github Identity Provider**.

Fine-grained Personal Access Token
| Organization Permission | Access Type | Purpose |
|  --- | --- | --- |
| Administration | `Read-only` | Retrieve and read the organization’s audit log |
| Members | `Read-only` | Retrieve data about the organization’s members |


Classic Personal Access Token
| Scope | Purpose |
|  --- | --- |
| read:audit_log | Retrieve and read the organization’s audit log |
| read:org | Retrieve data about the organization’s members |


## Generating Credentials

GitHub currently supports four methods of authenticating with its API. Synqly currently supports two of these methods with **the recommended method being to use a fine-grained personal access token.**

Fine-grained Personal Access Token
1. Log into GitHub with a user account that has a verified email address as well as permission to view all repositories in the organization that the Synqly integration will be configured for
2. Select your profile picture, then select **Settings**
3. Select **Developer settings** from the sidebar on the left
4. Select **Personal access tokens > Fine-grained tokens**
5. Select **Generate new token**
6. Fill in the field titled *Token name*
7. In the *Resouce owner* field, select the organization that the integration will be configured for
8. Select a token expiration date under the field titled *Expiration*
9. In the section titled *Repository access* select the **All repositories** option
10. In the section titled *Permissions* select **Add permissions** and add all of the required permissions and ensure that the listed access type aligns with the required permission access type. The required permissions and required permission access types can be found in the section above titled [Required Permissions](#required-permissions)
11. Select **Generate token**, take note of the value displayed and store it in a safe location
12. You have now created a new GitHub fine-grained personal access token. Proceed to the next section titled [Configuring the Integration](#configuring-the-integration)


For more information on fine-grained personal access tokens, see the [GitHub Managing your personal access tokens docs page](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens)

Classic Personal Access Token
1. Log into GitHub with a user account that has a verified email address as well as permission to view all repositories in the organization that the Synqly integration will be configured for
2. Select your profile picture, then select **Settings**
3. Select **Developer settings** from the sidebar on the left
4. Select **Personal access tokens > Tokens (classic)**
5. Select **Generate new token > Generate new token (classic)**
6. Fill in the field titled *Note*
7. Select a token expiration date under the field titled *Expiration*
8. Under the section titled *Select scopes* select each of the required permissions. The required permissions and required permission access types can be found in the section above titled [Required Permissions](#required-permissions)
9. Select **Generate token**, take note of the value displayed and store it in a safe location
10. You have now created a new GitHub classic personal access token. Proceed to the next section titled [Configuring the Integration](#configuring-the-integration)


For more information on classic personal access tokens, see the [GitHub Managing your personal access tokens docs page](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic)

## Configuring the Integration

To configure a new GitHub integration in the Synqly system, provide each of the values as defined below:

| Integration Parameter | Description |
|  --- | --- |
| Secret | This is the personal access token value generated from executing the steps above. |
| Organization Slug | This is the slug of the organization to which the Synqly integration will be tied to. This value can by found by navigating to your organization and viewing the url.  Example `https://github.com/organizations/{your-organization-slug}` |
| GitHub Instance URL | This is the url that you use to access your GitHub instance. This value is only required when using a url other than `https://github.com` |