# GitHub Connector > SailPoint GitHub SaaS Connector Documentation # Documentation # Connecting SailPoint and GitHub To connect SailPoint with GitHub, perform the following tasks: ## Adding the Source in SailPoint To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs. > [!IMPORTANT] > > By default, the provisioning feature is **disabled**, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration. **To configure a new source:** 1. Sign in to SailPoint. 2. Go to **Admin \> Connections \> Sources**. 3. Select **Create New**. 4. Search for the connector by entering the name in the search box, and then select **Actions**. 5. In the **Actions** dropdown list, select the setup method: - [**Express Setup**](<#configuring-a-source-using-express-setup>) - Quickly create a read-only connection to your target system by providing minimal configurations and authentication. On completion, aggregation is automatically started. > **Note** > > Express Setup supports Credential Providers. For information on supported credential providers and configuration, refer to [Credential Providers](). For more information, contact your SailPoint Customer Service Manager. - [**Standard Setup**](<#configuring-a-source-using-standard-setup>) - Provide detailed basic configuration to create the source. Once the source is created, continue with source setup. ### Configuring a Source Using Express Setup Express Setup minimizes the initial configuration process so you can quickly connect the application and immediately begin aggregating user account and entitlement data. 1. Review the directions and select **Start Express Setup**. 2. Review the pre-populated **Source Name**, **Source Owner**, and **Description**. To update, select **Edit**. > **Note** > > The source name must be unique. You can change these settings later in the source configuration. 3. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a Credential Provider in SailPoint, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 4. Configure the authentication to allow SailPoint to connect to the source. For more information, refer to the **Connection Settings** section. 5. Select **Finish**. After a successful test connection, the system creates your source and prompts you to run an aggregation. - If you want to aggregate now, select **Aggregate**. - To see the latest account aggregation history, go to **Account Management \> Account Aggregation**. - To see the list of aggregated source accounts, go to **Account Management \> Accounts**. - If you want to aggregate later, select **Exit**. This returns you to the **Sources** page. Your new source is listed, but contains no accounts or aggregation history yet. ### Configuring a Source Using Standard Setup Use Standard Setup to configure the connector for full feature support. 1. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters. 2. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters. 3. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](). 4. (Optional) Select a governance group to grant its members [source]() or [role]() sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](). 5. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](). 6. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there. ## Base Configuration Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary. 1. Enter a unique name and description for the source. 2. In the **Source Owner** dropdown list, select the identity that owns this source. - To find a source owner, begin entering their name. 3. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 4. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information. 5. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](). 6. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default. - **Enable Provisioning** - Set the toggle to **Enabled** to allow the source to create, update, and deactivate accounts in the connected source system. - **Disable Provisioning** - Set the toggle to **Disabled** to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source. 7. Select **Save**. ## Connection Settings The following information is required for SailPoint to connect and interact with GitHub. > [!NOTE] > > **Screenshot** > > [![Connection Settings]()]() 1. Enter the **Organization Name**. The Organization Name is the public profile name of the GitHub organization account (for example, acme-org). 2. Select an **Authentication Type** > **Note** > > Personal Access Token is the default authentication type. > **Personal access token** > > > **Screenshot** > > > > [![Personal Access Token]()]() > > 1. Select **Personal Access Token (PAT)** as the authentication type. > 2. Enter the **Personal Access Token (PAT)**. > The GitHub source uses a GitHub **Personal Access Token (PAT)** for authentication. 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 [https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token](). > 3. Select **Save**. > **GitHub App** > > > **Screenshot** > > > > [![GitHub App]()]() > > 1. Select **GitHub App** as the authentication type. > 2. Enter the **GitHub App ID** as the unique identifier for your GitHub App installation. > 3. Enter the **GitHub App private key** as the PEM-formatted private key generated for the GitHub App. > > > **Note** > > > > When you enter the private key you must 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. Enter the **Installation ID** as the installation identifier for your organization. You can obtain this from the GitHub App installation URL or through the GitHub API. 3. Select **Save**. ## Activity Insights Settings SailPoint pulls in activity data in the form of events like user logins, password changes, and content updates within the application. You can view an identity’s activity data within an application to discover trends for that user. > [!IMPORTANT] > > Contact your SailPoint Customer Success Manager (CSM) for more information on Activity Insights. For more information on utilizing activity data, refer to [Activity Insights](). Activity Insights Settings allows you to gather account information and activity data from GitHub. To enable Activity Insights for the GitHub application, refer to [Prerequisites]() for more information. To configure Activity Insights, complete the following: > [!NOTE] > > **Screenshot** > > [![Activity Insights Settings]()]() 1. Go to **Activity Insights Settings**. 2. Select **Enable Activity Insights** to view access to data insights on source and application activity such as logins and other app-specific events. 3. Select **Save**. ## Aggregation Settings > [!NOTE] > > **Screenshot** > > [![Aggregation Settings]()]() 1. Select **Aggregation Settings** from the menu. 2. Enter the **Page Size**. The Page size is the number of account and group records to aggregate in a single page when iterating over large datasets. The default page size is 100. 3. Select the option to **Aggregate Outside Collaborators**, if you want them to be managed as part of account aggregation. 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. 4. Select **Aggregate Repositories** to include repositories in the aggregation. 5. Select **Save**. ## Review and Test Perform a test to confirm the connection to SailPoint. 1. Go to **Review and Test**. 2. Confirm that the entries in each field are correct. If you note any mistakes, return to the section and make corrections. 3. Select **Test Connection**. ## SailPoint Application Onboarding SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface. For more information, refer to [Application Onboarding]() in the SailPoint SaaS documentation. # Dataset Management Dataset Management lets you review the object types a source collects and control how the source aggregates those objects into SailPoint. Use Dataset Management to view and manage resource attributes, datasets and their resources, enable dataset aggregation schedules, perform manual aggregation, and view aggregation history. > [!NOTE] > > Datasets are also available in SailPoint Agentic Fabric. Contact your Customer Success team and refer to [SailPoint Agentic Fabric]() for more information. For more information, refer to [Managing Datasets and Resources]() for datasets, resources, owner correlation, and aggregation. ## Datasets A *dataset* is a named group of one or more related resources that the source aggregates together. When aggregation runs for a dataset, the source collects all resources in that dataset from the managed system in one aggregation job. Activate or deactivate aggregation at the dataset level, not for individual resources. > [!NOTE] > > Each resource belongs to exactly one dataset for that source. The source defines which resources belong to each dataset. You can enable aggregation and review associated resources, but you cannot create or delete datasets or move resources between them. ### Dataset Aggregation Configure aggregation on the **Dataset Aggregations** tab for each dataset. Configure each dataset separately. During aggregation, your owner correlation rules are automatically applied to link machine identities to their human owners. For more information, refer to [Configuring Dataset Aggregations](). ## Resources A resource defines an object type from the managed system. It specifies the kind of object, the attributes the source collects, and how the source identifies and displays each object. Resources form the building blocks of the data model. In the UI, each resource appears under **Dataset Management** \> **Resources** with its schema. A resource does not run aggregation by itself. The dataset that owns the resource collects it during aggregation. For more information, refer to [Managing Resources](). ### Owner Correlation Configure owner correlation on each resource to link aggregated objects to human owners. If you do not configure owner correlation, or if the mapping produces no match, an owner is not assigned. For more information, refer to [Configuring Owner Correlation](). ## Supported Datasets Go to **Dataset Management \> Datasets** on your GitHub source to view the datasets the connector aggregates. Select a dataset to review its associated resources and configure aggregation. > [!NOTE] > > Configure aggregation for each dataset separately. For more information, refer to [Dataset Aggregation](). | Dataset Name | Associated Resources | Dataset ID | | --- | --- | --- | | GitHub App Installations | GitHub App Installations | `github:app-installations` | | GitHub Classic Personal Access Tokens | GitHub Classic Personal Access Token | `github:classic-pat` | | GitHub Copilot | GitHub Copilot | `github:copilot` | | GitHub Fine-Grained Tokens | GitHub Fine-Grained Token | `github:fine-grained-tokens` | | GitHub Environment Secrets | GitHub Environment Secret | `github:environment-secret` | | GitHub Workflows | GitHub Workflow, GitHub Action Run | `github:workflow`, `github:action` | ## Supported Resources A resource represents a type of object the connector collects from GitHub, such as fine-grained tokens, app installations, workflows, actions, or environment secrets. Each resource defines the attributes the connector collects for that object type and how SailPoint displays each object. For more information, refer to [Managing Resources](). > [!NOTE] > > When you enable dataset aggregation for a selected dataset, all resources in that dataset are collected at once. Activate or deactivate aggregation at the dataset level, not for individual resources. Go to **Dataset Management** \> **Resources** on your GitHub source to view each object type the connector aggregates. Select a resource to review its schema on the **Schema** tab. > [!NOTE] > > You need a valid SailPoint Entro license to view these resources in SailPoint: > > - GitHub Fine-Grained Token (Entro) > - GitHub Classic Personal Access Token > - GitHub Copilot Seat | Resource Name | Resource Type | Resource ID | | --- | --- | --- | | GitHub Fine-Grained Token | Credential | `github:fine-grained-token` | | GitHub App Installation | Account | `github:app-installation` | | GitHub Workflow | Application | `github:workflow` | | GitHub Action Run | Application | `github:action` | | GitHub Environment Secret | Credential | `github:environment-secret` | | GitHub Fine-Grained Token (Entro) | Credential | `github:entro-fine-grained-token` | | GitHub Classic Personal Access Token | Credential | `github:classic-pat` | | GitHub Copilot | Agent | `github:copilot` | | GitHub Copilot Seat | Agent | `github:copilot-seat` | ## GitHub Fine-Grained Token Attributes Schema attributes for the GitHub Fine-Grained Token resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Unique identifier of the fine-grained personal access token (PAT). | | name | string | Display name of the token. | | owner | string | GitHub login of the user who owns the fine-grained personal access token. | | access\_granted\_at | string | Timestamp indicating when organization access was granted to the token. | | expired | string | Indicates whether the token has expired. | | expires\_at | string | Expiration timestamp of the token. | | last\_used\_at | string | Timestamp indicating when the token was last used. | | permissions\_organization | string list | List of organization-level permissions retrieved from permissions.organization, represented as scope:access string pairs. | | permissions\_repository | string list | List of repository-level permissions retrieved from permissions.repository, represented as scope:access string pairs. | | repository\_full\_name | string | Full repository name in owner/repo format associated with the workflow. | | repository\_selection | string | Repository access scope of the token, such as none, all, or a subset of repositories. | ## GitHub App Installation Attributes Schema attributes for the GitHub App Installation resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Unique identifier of the GitHub App installation. | | name | string | Application slug associated with the installation. | | app\_id | string | GitHub App id. | | owner | string list | Human GitHub logins associated with the installation. | | permissions | string list | List of installation permissions retrieved from installation. permissions, represented as scope:access string pairs. | | repository\_selection | string | Repository access scope for the installation, either all or selected. | | target\_type | string | Type of installation target, such as Organization or User. | | created\_at | string | Timestamp indicating when the GitHub App installation was created. | | updated\_at | string | Timestamp indicating when the GitHub App installation was last updated. | | suspended | string | Indicates whether the installation is suspended. | | suspended\_at | string | Timestamp indicating when the installation was suspended, if applicable. | ## GitHub Workflow Attributes Schema attributes for the GitHub Workflow resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Unique workflow identifier. | | node\_id | string | Global GitHub node identifier for the workflow definition. | | name | string | Name of the workflow definition retrieved from the GitHub API. | | owner | string list | Human GitHub logins accountable for the workflow file. | | repository | string | Repository name only. | | repository\_full\_name | string | Full repository name in owner/repo format associated with the workflow. | | workflow\_id | string | Numeric GitHub workflow identifier. | | path | string | File path of the workflow definition within the repository. | | state | string | Current workflow state, such as active, deleted, disabled\_fork, or disabled\_inactivity. | | html\_url | string | URL of the workflow definition on GitHub. | | created\_at | string | Timestamp indicating when the workflow definition was created. | | updated\_at | string | Timestamp indicating when the environment was last updated. | ## GitHub Action Run Attributes Schema attributes for the GitHub Action Run resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Unique workflow run identifier. | | name | string | Title of the workflow run. | | node\_id | string | Global GitHub node identifier for the workflow run. | | status | string | Current status of the workflow run. | | head\_branch | string | Branch associated with the workflow run. | | actor | string | Login username of the user who created the workflow run. | | triggering\_actor | string | Login username of the user who triggered the workflow run. | | event | string | GitHub event that triggered the workflow run, such as push or pull\_request. | | run\_number | string | Sequential counter for the workflow within the repository. | | workflow\_id | string | Unique identifier of the parent workflow. | | workflow | string | Parent workflow label used for correlation. | | check\_suite\_id | string | Unique identifier of the check suite associated with the workflow run. | | repository | string | Full repository name in owner/repo format associated with the workflow run. | | owner | string list | Human GitHub logins accountable for the workflow run. | | created\_at | string | Timestamp indicating when the workflow run was created. | | updated\_at | string | Timestamp indicating when the workflow run was last updated. | ## GitHub Environment Secret Attributes Schema attributes for the GitHub Environment Secret resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Stable secret identifier in the format {owner}/{repo}/environment/{env}/secret/{name}. | | name | string | Name of the secret. | | scope | string | Scope of the secret. | | organization | string | Source organization in which the secret is configured. | | repository | string | Full repository name in owner/repo format associated with the secret. | | environment | string | Environment name owning the secret | | owner | string | Human GitHub logins accountable for this env-scoped secret - inherited from the parent environment's owner (env required reviewers; else repo admins; else organization owners). Bots filtered. | | created\_at | string | Timestamp indicating when the secret was created. | | updated\_at | string | Timestamp indicating when the environment was last updated. | ## GitHub Fine-Grained Token (Entro) Attributes Schema attributes for the GitHub Fine-Grained Token (Entro) resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Entro object id for the credential (e.g. TKN-44868). Optional in push attributes; identity is set from this field on the envelope. | | name | string | Display name for aggregation (same as token.name when present). | | source | object | Source account context from Entro. | | identity | object | Linked identity metadata from Entro. | | token | object | Core fine-grained PAT metadata from Entro. | | owners | object | Human owners accountable for the token. | | lifecycle | object | Token lifecycle timestamps from Entro. | | permissions | object | Fine-grained permissions granted to the token. | | tags | string list | Entro tags (e.g. organization slug). | | riskSeverity | string | Entro risk severity (e.g. LOW, MEDIUM, HIGH). | | complianceBreach | string list | Compliance rule identifiers triggered for this token. | | exposed | boolean | Whether Entro detected credential exposure. | | suspiciousActivity | boolean | Whether suspicious activity was flagged. | | lastUsedService | string | Last service that used the token (e.g. Github). | | extraData | object | Supplemental GitHub context from Entro. | | ownerEmail | string | Primary human owner email for ownership correlation. | ## GitHub Classic Personal Access Token Attributes Schema attributes for the GitHub Classic Personal Access Token resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Entro object id for the credential (e.g. TKN-16812). Optional in push attributes; identity is set from this field on the envelope. | | name | string | Display name for aggregation (same as token.name when present). | | source | object | Source account context from Entro. | | identity | object | Linked identity metadata from Entro. | | token | object | Core classic PAT metadata from Entro. | | owners | object list | Human owners accountable for the token. | | lifecycle | object | Token lifecycle timestamps from Entro. | | permissions | object list | OAuth scopes granted to the classic PAT. | | tags | string list | Entro classification tags (e.g. OAuth access token, integration name). | | riskSeverity | string | Entro risk severity (e.g. LOW, MEDIUM, HIGH). | | complianceBreach | string list | Compliance rule identifiers triggered for this token. | | exposed | boolean | Whether Entro detected credential exposure. | | suspiciousActivity | boolean | Whether suspicious activity was flagged. | | lastUsedService | string | Last service that used the token (e.g. Github). | | extraData | object | Supplemental GitHub context from Entro. | | ownerEmail | string | Primary human owner email for ownership correlation. | ## GitHub Copilot Attributes Schema attributes for the GitHub Copilot resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Stable seat or assignment identifier (UUID). Optional in push attributes; identity is set from this field on the envelope. | | name | string | Display name for the Copilot seat (e.g. github copilot). | | rawName | string | Raw client or editor identifier from the source (e.g. unknown/GitHubCopilotChat/0.37.9). | | agentType | string | Agent type label from discovery (e.g. GitHub Copilot Seat). | | classification | string | Prettified classification (e.g. Third-party, Homegrown). | | detectionMethod | string | How the agent was detected (e.g. GitHub Copilot Seat Assignment). | | sourceAccount | string | GitHub organization or account context for the seat. | | integrationType | string | Integration type (e.g. GITHUB). | | sourceUrl | string | Deep link to the source when available; empty when null in export. | | environment | string | Environment or organization slug from the source account. | | tags | string | Tags from discovery. | | insights | string | Human-readable insight strings from policy evaluation. | | owner | object | Human owner associated with the Copilot seat. | | lastSeen | string | ISO-8601 timestamp of last observed Copilot activity. | | riskBand | string | Risk severity band (e.g. UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). | | organizationName | string | GitHub organization name for the Copilot plan. | | planType | string | Copilot plan type (e.g. BUSINESS, ENTERPRISE). | | editor | string | Editor or client identifier last used with Copilot. | | lastAuthenticatedAt | string | ISO-8601 timestamp of last authentication for the seat. | ## GitHub Copilot Seat Attributes Schema attributes for the GitHub Copilot Seat resource. | Attribute | Type | Description | | --- | --- | --- | | id | string | Stable seat or assignment identifier (UUID). Optional in push attributes; identity is set from this field on the envelope. | | name | string | Display name for the Copilot seat (e.g. github copilot). | | rawName | string | Raw client or editor identifier from the source (e.g. unknown/GitHubCopilotChat/0.37.9). | | agentType | string | Agent type label from discovery (e.g. GitHub Copilot Seat). | | classification | string | Prettified classification (e.g. Third-party, Homegrown). | | detectionMethod | string | How the agent was detected (e.g. GitHub Copilot Seat Assignment). | | sourceAccount | string | GitHub organization or account context for the seat. | | integrationType | string | Integration type (e.g. GITHUB). | | sourceUrl | string | Deep link to the source when available; empty when null in export. | | environment | string | Environment or organization slug from the source account. | | tags | string | Tags from discovery. | | insights | string | Human-readable insight strings from policy evaluation. | | owner | object | Human owner associated with the Copilot seat. | | lastSeen | string | ISO-8601 timestamp of last observed Copilot activity. | | riskBand | string | Risk severity band (e.g. UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). | | organizationName | string | GitHub organization name for the Copilot plan. | | planType | string | Copilot plan type (e.g. BUSINESS, ENTERPRISE). | | editor | string | Editor or client identifier last used with Copilot. | | lastAuthenticatedAt | string | ISO-8601 timestamp of last authentication for the seat. | | ownerEmail | string | Primary human owner email for ownership correlation. | # 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]() 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](). ### 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]() 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](). ## 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](). ### 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 & 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//settings/installations/` - 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](). ## 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 # Machine Account Attributes ## Machine Account Provisioning Attributes Machine account creation uses the same attribute keys as standard account creation, but uses different generators. The following table lists the machine account creation attributes. | Attribute | Display Name | Type | Required | Generator | Description | | --- | --- | --- | --- | --- | --- | | email | Email | string | Yes | Static | The user's primary work email address. | | role | Role | string | Yes | Static | The role of the member in an organization. | For more information, refer to [Machine Identity Security Overview](). ### Classification The Classification attribute is used to identify and categorize the account as a Machine Account. - **Attribute name** - UserType - **Value** - Communication, Reference, Service, System # Provisioning The GitHub connector supports provisioning, allowing you to create and manage accounts and entitlements in GitHub directly from SailPoint. **Prerequisite:** Your system is configured for provisioning. When SailPoint provisions new accounts to the source, it uses the attributes on the **Create Account** page as instructions or a template for what to include in the account. This page is also referred to as the *provisioning policy*. When new access is granted on a source where a user does not already have an account, SailPoint automatically includes account creation in the provisioning. This applies whether provisioning is started from an access request or from an automated role or lifecycle state assignment. For direct-connect sources, SailPoint automatically creates the account from this configuration. If the source is not configured as a direct-connect source, SailPoint creates and assigns a provisioning task to the source owner and includes the values for the source owner to use in manually creating the account. > [!IMPORTANT] > > This section describes the default **Create Account** configuration. SailPoint recommends that you work with Services to define a provisioning configuration specific to your company's needs. Be sure to verify large changes to the provisioning policy before implementation. Failure to do so might cause provisioning to fail. ## Default Create Account Attributes | Account Attribute | Description | | --- | --- | | email | The email of the user. | | role | The role of the member in an organization. | > [!NOTE] > > - The **Role** is `default_member` by default. If you want to assign another value, `admin` and `billing manager` are additional values that you may use. > - An account must be created in GitHub by the end-user, and then the admin can invite the end-user to join an Organization. After the account is created, an invitation will be sent to the specified email address of the end-user. Once the invitation has been accepted, account aggregation must be performed on the source to correlate the identities. # Schema Reference The application schema is used to configure the objects returned from a connector. > [!NOTE] > > - The **Account Schema** tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as **Entitlement** or **Multi-Valued**. Refer to [Managing Source Account Schemas]() for more information. > - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified. The GitHub connector uses the following default correlation and object configurations. ## Default Correlation Configuration Before you aggregate accounts from this source, you can map account attributes with their corresponding identity attributes based on your requirements. You can customize the correlation configuration. Refer to [Assigning Source Accounts to Identities]() for more information. When you first create the GitHub source, the default correlation mapping is: | Account Attribute | Operation | Identity Attribute | | --- | --- | --- | | Email | Equals | Work Email (email) | | name | Equals | Name | ## Default Account Schema Each source supports a variety of details, or attributes, about each user who has an account, such as their name, email address, manager name, and location. The set of account attributes each source stores and how they're organized is known as the account's *schema*. To best represent your data, you can configure sources to use an account schema matching the one you use in the external connector. Refer to [Managing Source Account Schemas]() for more information. ### Default Account Attributes The GitHub connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified. | Attribute Name | Description | | --- | --- | | databaseId | Identifies the primary key from the database. | | login | The username used to login. | | name | The user's public profile name. | | id | The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. | | email | The user's publicly visible profile email. | | twitterUsername | The user's Twitter username. | | url | URL pointing to the user's public profile. | | bio | The user's public profile bio. | | bioHTML | The user's public profile bio as HTML. | | location | The user's public profile location. | | company | The user's public profile company. | | companyHTML | The user's public profile company as HTML. | | isBountyHunter | Whether or not this user is a participant in the GitHub Security Bug Bounty. | | isHireable | Whether or not the user has marked themselves as for hire. | | isEmployee | Whether or not this user is a GitHub employee. | | isSiteAdmin | Whether or not this user is a site administrator. | | isGitHubStar | Whether or not this user is a member of the GitHub Stars Program. | | isViewer | Whether or not this user is the viewing user. | | isCampusExpert | Whether or not this user is a participant in the GitHub Campus Experts Program. | | isDeveloperProgramMember | Whether or not this user is a GitHub Developer Program member. | | hasSponsorsListing | True if this user/organization has a GitHub Sponsors listing. | | followers | The number of users the given user is followed by. | | following | The number of users the given user is following. | | gists | The number of gists the user has created. | | repositories | The number of repositories that the user owns. | | watching | The number of repositories that the user is watching. | | estimatedNextSponsorsPayoutInCents | The estimated next GitHub Sponsors payout for this user/organization in cents (USD). | | monthlyEstimatedSponsorsIncomeInCents | The estimated monthly GitHub Sponsors income for this user/organization in cents (USD). | | websiteUrl | A URL pointing to the user's public website/blog. | | createdAt | Identifies the date and time when the user was created. | | updatedAt | Identifies the date and time when the user was last updated. | | teams | A list of teams the user is a member of. | | role | Role of the member . | | samlNameId | The SAML name id of the user. | | repositoryIDs | The repositories user has access to. | > [!NOTE] > > For existing sources, add this attribute explicitly through the UI. ## Default Entitlement Attributes Entitlement attributes define the entitlements, such as groups or roles, that can be assigned to the managed system's user accounts. Refer to [Managing Entitlements]() for more information. > [!CAUTION] > > Changing the attribute marked as the Entitlement ID after aggregating accounts or entitlements can result in duplicate entitlements being created, or access profiles and roles breaking. To avoid this, edit the entitlement schema before performing any aggregations. ### Default Group Attributes The GitHub connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups. | Attribute Name | Description | | --- | --- | | databaseId | Identifies the primary key from the database. | | slug | The slug corresponding to the team. This is an Entitlement ID. | | name | The name of the team. This is an Entitlement name. | | id | The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. | | description | The description of the team. | | privacy | The level of privacy the team has. | | combinedSlug | The slug corresponding to the organization and team. | | url | URL pointing to the team's page. | | members | A number of users who are members of this team. | | repositories | Indicates the number of repositories who are part of this team. | | parentTeam | The parent team of the team. | | createdAt | Identifies the date and time when the object was created. | | updatedAt | Identifies the date and time when the team was last updated. | | permission | The permission a team has. | | role | Role of the member. | | repositoryNames | The repositories team has access to. | > [!NOTE] > > To add `permission` attribute in the Entitlement Schema use [Update Source Schema (Partial)]() API. ### Default Role Attributes The GitHub connector supports roles. The following attributes must be configured on the managed system and in the SailPoint source schema to manage roles. | Attribute Name | Description | | --- | --- | | id | The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. This is an Entitlement ID. | | name | The name of the role. This is an Entitlement name. | ### Default Repository Attributes The following lists the repository attributes: | Attribute Name | Description | | --- | --- | | id | Identifies the primary key from the database. This is an Entitlement ID. | | name | The name of the repository. This is an Entitlement name. | | permission | The permission of the repository. | | visibility | The visibility of the repository. | # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## Debug Logs For information about managing additional source settings, including debug logging and downloading connector logs, refer to [Managing Additional Settings](). ## Account aggregation failing with "connector process may have crashed" **Resolution** - Add `aggregateTimeout` in application to resolve the issue. ```json [ { "op": "replace", "path": "/connectorAttributes/aggregateTimeout", "value": 3600 } ] ``` ## 502 error during account aggregation An account aggregation process fails with the following error message: ```text java.lang.IllegalStateException: [ConnectorError] 502 Unknown error: {"data":null,"errors":[{"message":"Something went wrong while executing your query. This may be the result of a timeout, or it could be a GitHub bug. ``` **Resolution** - If you continue to encounter the error, continue to reduce the page size setting until the process is successful. For example, reduce the page size incrementally from 100 to 50, then to 40, 30, and 20. ## GitHub Roles not aggregating correctly GitHub roles associated with an account are not aggregating properly in SailPoint. **Resolution** - Change the Role attribute type from `String` to `Role` in Account Schema . Save and re-aggregate the source. ## Account aggregation failing with error: Resource limits for this query exceeded with HTTP 429 During account aggregation, the process fails and returns an HTTP 429 error, indicating that the resource or API rate limits have been exceeded. **Resolution** - If you continue to encounter the error, continue to reduce the page size setting until the process is successful. For example, reduce the page size incrementally from 100 to 50, then to 40, 30, and 20. ## Teams provisioning fails for a new user when no role is assigned ```text [ConnectorError] Account updates failed. Cannot read properties of undefined (reading 'role') ``` **Resolution** - - A user must be an active member of the GitHub organization with at least a base role (Member or Owner) before a team can be assigned. - Instruct the user to accept the GitHub organization invitation. - Once the user accepts and a role is assigned, team provisioning will complete successfully. - Verify if the user currently has a role assigned in the GitHub organization. ## Provisioning may fail intermittently with the error ''sp-connect command timed out'' **Resolution** - Increase the timeout configuration values and retry the provisioning workflow: - Set `aggregateTimeout` to 3600 seconds. - Set `provisioningTimeout` to 600 seconds. After updating these values, re-run the provisioning use case to confirm successful completion. ```json [ { "op": "add", "path": "/connectorAttributes/aggregateTimeout", "value": "3600" }, { "op": "replace", "path": "/connectorAttributes/provisioningTimeout", "value": "600" } ] ``` # Upgrade Considerations For existing sources, the following changes must be completed: - Add the provisioning policy using the API for [create-provisioning-policy | SailPoint Developer Community.]() - Add `PROVISIONING` in the feature string of the source using the API for [update-source | SailPoint Developer Community](). - Add `samlNameId` in account schema via below API [update-source schema| SailPoint Developer Community](). - Add a new entitlement type Role with the following two attributes using the API for [update-source schema (partial)| SailPoint Developer Community.]() - id- Identifies the primary key from the database. - name- The name of the role.