## 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 Application Security 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 permission to view all repositories in the organization that the Synqly integration will be configured for


## Required Permissions

Fine-grained Personal Access Token
| Repository Permission | Access Type | Purpose |
|  --- | --- | --- |
| Metadata | `Read-only` | Retrieve data about the organizations repositories |
| Code scanning alerts | `Read-only` | Retrieve a repositories Dependabot alerts |
| Dependabot alerts | `Read-only` | Retrieve a repositories Code Scanning alerts. |


Classic Personal Access Token
| Scope | Purpose |
|  --- | --- |
| repo.security_events | Retrieve a repositories Dependabot and Code Scanning alerts |


## 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* field
7. In the *Resouce owner* field, select the organization that the integration will be configured for
8. Select an 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 an 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 in 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` |