> For the complete documentation index, see [llms.txt](https://docs.dropzone.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dropzone.ai/integrations/data/github.md).

# GitHub

Dropzone AI interfaces with [GitHub](https://github.com/about), a software building platform. Dropzone integrates with GitHub's [security features](https://docs.github.com/en/code-security/getting-started/github-security-features) to identify data breaches or secret/credential leaks in your projects.

To integrate with GitHub, you must have purchased [GitHub Secret Protection](https://docs.github.com/en/code-security/concepts/secret-security/secret-security-with-github#github-secret-protection).

## Integration Overview

To enable these integrations you will perform the following actions:

* Enable GitHub Secret Protection in your organization or repositories
* Create a Classic Personal Access Token with the necessary roles and permissions
* Enable the Data source in your Dropzone tenant

## Enable GitHub Secret Protection

If you have not already enabled GitHub Secret Protection in the organization or repositories you want Dropzone to have access to, you must do so now.

To enable security features at a repository level, you must be a repository owner or user with Admin privileges. Do the following:

* In each repository you want Dropzone to scan, navigate to Settings
* In the left sidebar, navigate to Security and quality > Advanced Security
* Click "Enable" to the right of the features you want to activate

To enable security features at an organizational level, you must be an organization owner or user with Admin privileges. Do the following:

* Open your [organizations page](https://github.com/settings/organizations)
* Select the organization you want Dropzone to access, then click "Settings"
* In the left sidebar, navigate to Security > Advanced Security > Configurations
* Click "New Configuration"
* Click "Custom configuration"
* Name your configuration something memorable, such as "Dropzone AI Configuration"
* Enable the features you wish to enable, then click "Save configuration"

See [here](https://docs.github.com/en/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/create-custom-configuration#creating-a-secret-protection-and-code-security-configuration) for a list of possible features and information on advanced security customization.

Once you have created your organization configuration, you must apply them to individual repositories.

To do so, do the following:

* In the Configurations page of your organization's security settings, click "Repositories"
* Select each repository you want Dropzone to access
* Click "Apply configuration"
* Select the custom security configuration you just created
* Click "Apply"

Each repository's [configuration status](https://docs.github.com/en/code-security/reference/security-at-scale/configuration-statuses) should show the configuration as `attached`. If you have any errors, engage your GitHub support representative.

## Create a Personal Access Token

GitHub requires a [Classic Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) to configure.

To obtain an Access Token, do the following:

* As an organization owner, navigate to your [GitHub](https://github.com/dashboard) account
* Click your profile picture in the upper right
* Click "Settings"
* In the left sidebar, click "<> Developer settings"
* In the left sidebar, navigate to Personal access tokens > Tokens

{% hint style="info" %}
Alternatively, open the [Tokens page](https://github.com/settings/tokens) directly.
{% endhint %}

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FT1nWs5KrrdnMymDmiPZv%2Fgithub-1.png?alt=media" alt=""><figcaption></figcaption></figure>

* Click "Generate new token" then select "Generate new token (classic)"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F5CAZS9fDcGTZv27WHgrN%2Fgithub-2.png?alt=media" alt=""><figcaption><p>Create a Classic Personal Access Token</p></figcaption></figure>

* In the Note section, name the token something memorable, such as "Dropzone AI"
* Set an expiration date for the token

{% hint style="warning" %}
Your Dropzone integration will stop working when the client secret expires. For convenience's sake, we recommend picking a longer expiration date, to limit the number of times the access token must be updated.
{% endhint %}

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F5GrIoQco0LqxVNLr7Qbh%2Fgithub-3.png?alt=media" alt=""><figcaption></figcaption></figure>

* Assign the token the following scopes:

| Scope             | Purpose                                                                                                                                                                                             |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:audit_log`  | Retrieve [audit log data](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) |
| `read:org`        | Retrieve information about organization membership, organization projects, and team membership                                                                                                      |
| `security_events` | Grants read and write access to [security events](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/security-log-events) in the code scanning API                      |

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F7nM7asCopOBZbODmIfqz%2Fgithub-4.png?alt=media" alt=""><figcaption><p>Example: Assign the `security_events` Scope</p></figcaption></figure>

* Click "Generate token"
* Copy the personal access token shown for use later in the Dropzone UI

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FIKuhyQxGZAalXFv5yX5J%2Fgithub-5.png?alt=media" alt=""><figcaption><p>Copy the Personal Access Token</p></figcaption></figure>

## Enable GitHub

To enable the Data Source integration, you will need the following information:

| Dropzone Field        | Source                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Organization          | Your organization name                                                                                                                                                                                                                                                                                                                                       |
| Personal Access Token | The Personal Access Token (PAT) value you generated earlier                                                                                                                                                                                                                                                                                                  |
| Enterprise (optional) | Your [enterprise slug](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-your-enterprise-account/changing-the-url-for-your-enterprise#about-changes-to-enterprise-slugs), e.g. <https://github.com/enterprises/_my-enterprise-slug>\_. Inputting this will allow Dropzone to search every organization within the enterprise the PAT can see |
| API URL               | The API URL your organization uses, e.g. *<https://api.github.com>*, *<https://api..ghe.com>*, or *https\:///api/v3*                                                                                                                                                                                                                                         |

To enable the Data Source integration, do the following:

* Navigate to your Dropzone AI tenant home page e.g. https\://*mycompany*.dropzone.app
* In the left side bar, navigate to Platform Settings > Integrations

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FQKQGU2YK0KqsewZWvh0i%2Fui-integrations-dropdown.png?alt=media" alt=""><figcaption><p>Integrations Dropdown</p></figcaption></figure>

* Click "Library"

{% hint style="info" %}
If you have previously integrated this application, click "Configured"
{% endhint %}

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fx4O3FuRG5IqPwx5sFuHr%2Fapp_system_integrations_library.png?alt=media" alt=""><figcaption><p>Click Library</p></figcaption></figure>

* In the Search bar, search GitHub, then click "Configure"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F433HqhRP6rXdk1dBsqVC%2Fapp_system_integrations_library_github.png?alt=media" alt=""><figcaption><p>The GitHub Data Tile</p></figcaption></figure>

* Input the Organization, Personal Access Token, Enterprise (optional) and API URL

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FWTjlZn2svmbwrMn9BnZC%2Fapp_system_integrations_library_github_config.png?alt=media" alt=""><figcaption><p>The GitHub Configuration (pt 1)</p></figcaption></figure>

* If you wish to guide Dropzone's AI agent in querying data, check "Enable" under "Query guidance"
* Click "Add Item", then input conditions and instructions for the AI
* Contact our Customer Success team for more information about this feature

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FSFsGGZDQ7Dxw2JTL6ibZ%2Fquery-guidance-test-save.png?alt=media" alt=""><figcaption><p>The GitHub Configuration (pt 2)</p></figcaption></figure>

* Click "Test & Save" to finish

If you have any errors contact our Customer Success team.
