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

# Github

{% hint style="warning" %}
Warning: The Identity Intelligence Github integration is currently being moved away from a classic PAT installation to a Github app installation and is currently in Alpha. New PAT installations have been disabled, and existing Github integration customers will soon be notified to start migrating to the new installation method. If you would like early access to this new installation path please contact your Duo Care team, Duo Support or open a Cisco TAC Case to enable it in your account.
{% endhint %}

## Overview <a href="#overview" id="overview"></a>

Identity Intelligence can connect to Github Enterprise tenants and provide insights into user identities and activity on that platform.

This document will walk you through the process of setting up access from Identity Intelligence to Github Enterprise.

### Requirements <a href="#next-steps" id="next-steps"></a>

The following requirements are necessary for the Github integration -

1. Github Enterprise subscription
2. A Github **Enterprise admin account** capable of creating and installing [Github Apps](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise) on the enterprise.
3. SSO from your Identity Provider to **each** Github org is set to "Enforced" (mandatory) and **not** "Configured" (optional), otherwise Identity Intelligence cannot retrieve the emails for users in the "configured" org and they will not merge with their own record in the "enforced" org.

## Github API Permission Structure

### Enterprise vs. Org

Identity Intelligence has chosen to connect to Github environments at the Enterprise level rather than per Organization. This allows for the use of one Github app for an entire customer environment, instead of a Github app being required for each Org.

Therefore, an Enterprise Admin account or an Enterprise service account is required.

### Only Include Specific Github Orgs

Please see [Github Configuration Steps, step 8](#github-configuration-steps) to see how to configure Identity Intelligence to only collect the data for specific orgs under your enterprise.

### Compatible Checks

Currently, 17 security posture and threat detection Checks are compatible with the Github integration. Identity Intelligence is continuously adding to this list, based on customer requests and also new and emerging identity-based threats for Github.

<figure><img src="/files/AOv8co9347Ri0Qo6c2Lz" alt=""><figcaption></figcaption></figure>

## Github Configuration Steps <a href="#github-configuration-steps" id="github-configuration-steps"></a>

1. Login to Github with an **Enterprise admin account.** If you navigate to [Github.com/settings/enterprises](https://Github.com/settings/enterprises), it should look something like the following:

   <figure><img src="/files/zqa4wq9hxiKbIVeEepU6" alt=""><figcaption></figcaption></figure>
2. Enable **displaying IP addresses in the Github Audit Log** for your enterprise tenant as described in [this article](https://docs.Github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise#enabling-display-of-ip-addresses-in-the-audit-log)
3. Follow the steps for registering a GitHub app as outlined in this [Github article](https://docs.github.com/en/enterprise-cloud@latest/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
   1. In step 2 make sure you follow the directions for apps owned by an enterprise.
   2. In step 7 enter the URL to your Identity Intelligence dashboard.
   3. Skip steps 8-13.
   4. Complete step 14 to disable the webhook.
   5. For step 18 configure the following permissions:
      * Repository permissions:
        * Actions
        * Administration
        * Contents
        * Custom properties
        * Dependabot secrets
        * Deployments
        * Discussions
        * Issues
        * Metadata (mandatory)
        * Projects
        * Pull requests
        * Secret scanning alert dismissal requests
        * Secret scanning alerts
        * Secret scanning push protection bypass requests
        * Secrets
      * Organization permissions:
        * Administration
        * Blocking users
        * Custom organization roles
        * Custom properties
        * Custom properties for organizations
        * Custom repository roles
        * Events
        * GitHub Copilot Business
        * Issue fields
        * Issue types
        * Members
        * Models
        * Organization dependabot secrets
        * Personal access tokens
        * Projects
        * Secrets
      * Enterprise Permissions:
        * Custom enterprise roles
        * Custom properties
        * Enterprise AI controls
        * Enterprise custom organization roles
        * Enterprise custom properties for organizations
        * Enterprise organization installation repositories
        * Enterprise organization installations
        * Enterprise people
        * Enterprise single sign-on
4. Once you have registered your new app you will need to generate and save a private key. Once you generate the key the file should automatically be downloaded for you. You will need to input this private key into Identity Intelligence later.
5. Press **save changes** in the Github app screen. In the **general** page note the **app ID** at the top of the page, you will need this later.
6. Go to the **Install App** page inside your new app. Your screen should look something like this:

   <figure><img src="/files/YhBqQarHlLizyHmY6ooo" alt=""><figcaption></figcaption></figure>
7. Press **install** on your enterprise and accept the permissions that you configured in step 3.
8. Optionally, if you would like to control which organizations Identity Intelligence collects data from you should go back to the **Install App** screen in the Github app's settings and install it on every organization you would like Identity Intelligence to monitor.
9. Note the **slug** for your Enterprise Github tenant. This can be found under your enterprise profile tab.

   <figure><img src="/files/L9MMiSw0Ld4nZpbkTxnL" alt=""><figcaption></figcaption></figure>

## Identity Intelligence Configuration Steps

Sign in to your Identity Intelligence tenant and perform the following steps:

{% hint style="info" %}
If you installed your Github app on multiple **Github enterprises** you will have to repeat this section once per enterprise.
{% endhint %}

1. From the Integrations page, click **Add Integration** and select **Github**.
2. Enter a display name for the integration, such as *Github \<your enterprise name>*.
3. Enter the value of your Github Enterprise slug, obtained in Step 9 above.
4. If you are migrating to the app installation type, select **app** as the authentication type. Otherwise, this will automatically be done for you.
5. Enter the Github app's application ID from step 5 above.
6. Enter the Github app's secret value that was downloaded for you in step 4 above.

   <figure><img src="/files/CdoeoFFpHYF31sNCiJx5" alt=""><figcaption></figcaption></figure>
7. Once the configuration connection is successful, go back to the main **Integrations** page, click the 3-dot menu on the Github integration and select **Collect Now**. Collection may take some time, depending on the size of the environment.

   <figure><img src="/files/k5o6rK0CNCjtPIRAScNZ" alt=""><figcaption></figcaption></figure>

## Github Event Streaming (Beta) <a href="#github-event-streaming" id="github-event-streaming"></a>

{% hint style="warning" %}
GitHub has no plans to take audit log streaming out of private beta. So if you are not already in the beta program you will not be able to use this feature.
{% endhint %}

Github has the capability to [streaming the audit log events](https://docs.Github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). This is currently in Beta. If you do not see the option in your Github Enterprise tenant, contact your Github representative.

Note: The Github base configuration above must already be completed. This step is highly recommended.

1. Within CII, navigate to Integrations and click **Edit Settings** on the existing Github integration.
2. Click the **Event Streaming** tab.
3. Slide the button to **Use Audit Log Streaming**.
4. Note the **Domain**, **Path**, and **Port** information for use in the Github setup.
5. Create a strong value for the **Webhook Secret** and enter it in the config.

   <figure><img src="/files/1Lein4U1Q588da0fpJsu" alt=""><figcaption></figcaption></figure>
6. Within Github, navigate to **Settings** > **Audit Log** > **Settings**. Ensure that `Enable API Request Events` is checked.

   <figure><img src="/files/HmrrsObnjQauOcvN8O9N" alt=""><figcaption></figcaption></figure>
7. On the **Log Streaming** tab, select `HTTP Event Collector` from the **Configure stream** dropdown list.

   <figure><img src="/files/c1ZJIb7GyN8axv7epooE" alt=""><figcaption></figcaption></figure>
8. Enter the **Domain**, **Path**, **Port**, and **Token** (Webhook secret above).
9. Check the `Enable SSL verification` button.

   <figure><img src="/files/47aGf1khJuuqXHfSH36X" alt=""><figcaption></figcaption></figure>
10. Back in the CII integration settings, click the checkbox to confirm that you have configured Github streaming in that platform and then click `Save`.

    <figure><img src="/files/tin68EP4tBiMCDc05JaK" alt=""><figcaption></figcaption></figure>
11. Back on the Github streaming configuration page, click the `Check endpoint` button. Once successful, click `Save`.

    <figure><img src="/files/27nlTwPMsHTbeTei8fIT" alt=""><figcaption></figcaption></figure>
12. That's it. It should be all set.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.oort.io/integrations/github.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.