# Integrating SailPoint with GitHub

Use the GitHub source to manage identity and access in the GitHub application. The GitHub source connects to the GitHub application securely to load data from and provision changes.

This document is designed to give specific information about the requirements and fields needed to successfully configure an instance of the GitHub source.

> [!NOTE]
>
> To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes](<https://community.sailpoint.com/release-notes/saas>) page.

## Onboard GitHub with SailPoint Agentic Fabric (SAF)

SailPoint Agentic Fabric (SAF) provides an automated, guided onboarding experience to connect your GitHub environment to SailPoint. SAF automatically creates, deploys, and configures the GitHub SaaS source in SailPoint, reducing the manual setup steps. After onboarding, the source is ready for aggregation and governance.

For detailed onboarding instructions, prerequisites, and supported deployment models, refer to [Configuring the GitHub SaaS Connector](<#configuring-the-github-saas-connector>).

> [!IMPORTANT]
>
> To enable advanced governance capabilities for GitHub resources and AI agents, an active SailPoint Agentic Fabric Advanced Governance license is required. Contact your SailPoint Customer Success Manager to request access and for more information.

## Configuring the GitHub SaaS Connector

To configure the GitHub SaaS connector in SailPoint Agentic Fabric (SAF), provide the GitHub organization and authentication details. SAF uses these values to create and configure the GitHub SaaS source in SailPoint so the source is ready for aggregation and governance.

**To configure the GitHub SaaS connector:**

1. In **Organization Name**, enter the public profile name of the GitHub organization account. For example, `acme-org`.
2. For **Authentication type**, select **Personal access token** or **GitHub App**.

   > **Note**
   >
   > Use a personal access token (PAT) or a GitHub App installation. Leave the selection as **Personal access token** when using a token.

### Personal Access Token

**If you select Personal access token:**

1. Select **Personal access token**.
2. Enter the personal access token. The token must have the `admin:org` and `user` scopes granted in the GitHub organization account. To create a token, refer to [Managing your personal access tokens](<https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token>).

### GitHub App

To use GitHub App authentication, create and install a GitHub App in your organization. For the required permissions, refer to [Required Permissions](<#required-permissions>). For the steps to create the app, refer to [Prerequisites](<#prerequisites>).

**If you select GitHub App:**

1. Select **GitHub App**.
2. In **GitHub App ID**, enter the numeric App ID from your GitHub App settings (Developer settings).
3. In **GitHub App private key**, enter the PEM private key generated for the GitHub App, including the BEGIN and END lines.

   > **Note**
   >
   > Enter the whole private key, including the BEGIN PRIVATE KEY and END PRIVATE KEY lines. For example:
   >
   > ```text
   > -----BEGIN ENCRYPTED PRIVATE KEY-----
   > *HASH VALUE*
   > -----END ENCRYPTED PRIVATE KEY-----
   > ```
4. In **Installation ID**, enter the installation ID for this organization. You can obtain this value from the GitHub App installation URL or through the GitHub API.

**To save the configuration:**

1. Select **Save**.

## Supported Features

The GitHub connector supports the following features:

#### Account Management

- Manage GitHub Accounts for a specific GitHub Organization
- Account aggregation and refresh
- Add and remove entitlements
- Send an invite email to users who are joining a GitHub Organization during the Create Account operation
- Managing Account aggregation for Outside Collaborator

  - An outside collaborator is a person who is not a member of the organization, but has access to one or more of the organizations repositories.

#### Entitlement Management

- Manage GitHub teams as entitlements
- Aggregation of entitlements

  - Aggregation of teams as entitlements
  - Aggregation of roles as entitlements

#### Non-Human Identity Discovery

The connector aggregates the following machine identity types:

- Fine-grained token
- GitHub applications
- GitHub workflows
- GitHub actions
- GitHub environment secrets
- GitHub personal access tokens
- GitHub Copilot

Refer to [Discovering Potential Non-Human Accounts](<https://documentation.sailpoint.com/saas/help/agentic_fabric/nhi/non_human_accounts.html#discovering-potential-non-human-accounts>) for more information.

#### Non-Human Identity Governance

1. Identify and track non-human identities

   - Supports GitHub fine-grained tokens and GitHub IAM users
   - Ingest and correlate GitHub audit logs
2. Monitor GitHub secrets for vaulted secrets management
3. Continuously scan repositories for exposed secrets across the following (coming soon):

   - Code commits for main and side branches
   - PR descriptions
   - PR code review comments
   - Workflow logs

#### Activity Insights

Activity Insights supports activity from GitHub and its associated accounts. This allows you to gather account information and activity data from GitHub.

> [!IMPORTANT]
>
> Contact your SailPoint Customer Success Manager (CSM) for more information on Activity Insights. For more information on configuring Activity Insights, refer to Activity Insights Settings.

For more information on features, refer to [Source Features](<https://community.sailpoint.com/knowledge/Identity-Security-Cloud-Source-Features>).

## Prerequisites

The GitHub source uses a GitHub **Personal Access Token** (**PAT**) or a **GitHub App** for authentication.

### Personal Access Token

The personal access token must have `admin: org` and `user` scopes granted in the GitHub organization account. To learn how to create a **PAT**, refer to [Managing your personal access tokens](<https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token>).

### GitHub App

To use GitHub App authentication or aggregate machine identities, create and install a GitHub App in your organization. Grant the app the permissions listed in [Required Permissions](<#required-permissions>).

**To create a GitHub App:**

1. **Open GitHub App settings**

   - Go to your **organization** \> **Settings** \> **Developer settings** \> **GitHub Apps** \> **New GitHub App**.
2. **Fill in app details**

   - **Name** (required)
   - **Homepage URL** (required)
   - **Webhook**: Set to **Inactive** if you only need API access.
   - **Where can this app be installed?**: Select **Only on this account** for one organization.
3. **Set permissions**

   - Under **Permissions**, select the permissions the app requires. For example, organization **Members**, **Administration**, and repository **Metadata**.
   - Start with **Read**. Use **Read &amp; write** only if you need provisioning.
   - For more information, refer to [Required Permissions](<#required-permissions>).
4. **Create the app**

   - Select **Create GitHub App**.
5. **Generate a private key**

   - On the app page, go to **Private keys** \> **Generate a private key**.
   - Save the downloaded `.pem` file securely.
6. **Note the App ID**

   - On the same page, copy the numeric **App ID**.
7. **Install the app on your organization**

   - In the app sidebar, go to **Install App** \> select your **organization** \> **Install**.
   - Select **All repositories** or **Only select repositories**.
8. **Get the Installation ID**

   - After you install the app, the URL looks like: `https://github.com/organizations/<org>/settings/installations/<installation-id>`
   - Copy the **installation ID** number.

#### For Activity Insights

An administrator requires the following additional permission to utilize the Activity Insights:

| Scope | Description |
| --- | --- |
| repo | Full control of private repositories. |

For more information on configuring Activity Insights, refer to [Activity Insights Settings](<https://documentation.sailpoint.com/connectors/github/saas/help/connecting.html#activity-insights-settings>).

## Required Permissions

The GitHub source requires specific GitHub App permissions for account management and machine identity aggregation.

### GitHub App Permissions for User Management

| GitHub App permission | Level | Used by |
| --- | --- | --- |
| Organization \> Members | Write | Account update (team membership) |
| Organization \> Administration | Write | Account create (organization invitation) |
| Repository \> Administration | Read | Outside collaborator aggregation |
| Repository \> Metadata | Read | Repository entitlement aggregation |

### Permissions Required for Each Resource

| Dataset name | Permission |
| --- | --- |
| **GitHub Apps** | Read permission to Organization - Administrator |
| **GitHub Actions** | Read permission to Repository - Actions |
| **GitHub Workflows** | Read permission to Repository - Actions |
| **Environment Secrets** | Read permission to Repository - Environment |

### GitHub App Required Scopes for Machine Identity Aggregation

Configure the following permissions on the GitHub App. Select **All repositories** for repository access.

#### Repository Permissions - Read-only

- Actions
- Administration
- Attestations
- Checks
- Code scanning alerts
- Codespaces
- Codespaces lifecycle admin
- Codespaces metadata
- Commit statuses
- Contents
- Custom properties
- Dependabot alerts
- Dependabot secrets
- Deployments
- Discussions
- Environments
- Issues
- Merge queues
- Metadata (mandatory)
- Packages
- Pages
- Projects
- Pull requests
- Repository security advisories
- Secret scanning alerts
- Secrets
- Variables
- Webhooks

#### Organization Permissions - Read-only

- Administration
- Blocking users
- Custom organization roles
- Custom properties
- Custom repository roles
- Events
- GitHub Copilot Business
- Members
- Organization Copilot metrics
- Organization announcement banners
- Organization codespaces
- Organization codespaces secrets
- Organization codespaces settings
- Organization dependabot secrets
- Personal access token requests
- Personal access tokens
- Plan
- Projects
- Secrets
- Self-hosted runners
- Variables

#### Organization Permissions - Read-and-write

- Webhooks

#### Account Permissions - Read-only

- Block another user
- Codespaces user secrets
- Copilot Chat
- Email addresses
- Followers
- GPG keys
- Git SSH keys
- Interaction limits
- Plan
- SSH signing keys
- Starring
- Watching