# GitHub

## Overview

The GitHub integration enables Veza to authenticate with GitHub organizations and discover users, repositories, teams, and other [entities](#notes-and-supported-entities), along with searchable metadata (attributes) for these entities. Veza will also map external corporate identities (such as Azure AD Users) to granular GitHub Roles and Permissions.

After configuring the integration you can use Workflows and Search to review access to public and private GitHub repositories within your organization. Built-in *Saved Queries* for GitHub are available for customization and use in [Dashboards](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards.md).

This integration supports self-managed and cloud-hosted GitHub environments, including:

* GitHub Cloud (e.g. Organizations on github.com)
* GitHub Enterprise Cloud
* GitHub Enterprise Server

> **Note:** This integration requires a GitHub App installed on one or more GitHub **organizations**. Standalone personal GitHub accounts (accounts without an organization) are not supported as a connection target.

For self-managed GitHub deployments, you should use an [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) to enable the connection, or allow traffic from Veza's [cloud IPs](/4yItIzMvkpAvMVFAamTf/integrations/connectivity.md).

## Enable Lifecycle Management

The GitHub integration supports Lifecycle Management capabilities for user provisioning, team management, and de-provisioning. LCM can invite users to GitHub organizations, manage team memberships, and suspend accounts during offboarding workflows.

Supported LCM actions include:

* **Sync Identities:** Create and update user accounts with email addresses and profile information
* **Manage Relationships:** Add or remove users from organizations and teams
* **De-provision Identity:** Suspend user accounts and remove all access relationships

To enable LCM functionality, your GitHub App requires additional write permissions beyond the basic read-only permissions:

* Organization permissions - Members (Write)
* Organization permissions - Administration (Write)
* Repository permissions - Administration (Write)

**Note**: LCM operations use GitHub Admin API endpoints that require site administrator privileges. These operations are only available for GitHub Enterprise Server environments.

For detailed LCM configuration and examples, see the [GitHub Lifecycle Management guide](/4yItIzMvkpAvMVFAamTf/integrations/integrations/github/provisioning.md).

## Configuration

To authenticate with GitHub, you will need to create a Github App granting Veza access your organization to gather the necessary information. See the instructions for:

* [creating a read-only GitHub App](#github-setup-instructions) for Veza, and install it into the GitHub organizations to discover.
* [adding the integration to Veza](#veza-setup-instructions) with the GitHub App's credentials.

To integrate with several organizations with a single GitHub App and Veza integration configuration, you can:

1. Create the GitHub app.
2. Set it to Public.
3. Install the app into each GitHub organizations to discover.

For more details, see the GitHub documentation [Creating GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/creating-github-apps/creating-a-github-app) and [Making a GitHub App Public or Private](https://docs.github.com/en/apps/creating-github-apps/creating-github-apps/creating-a-github-app).

### GitHub setup instructions

To create and register the application within an organization you administer, open GitHub **Settings** > **Organizations**. Click *Settings* next to the name of the organization containing the members, repositories, and permissions to extract.

> If you are not an org admin, you can create the app under your personal **Developer Settings** > **GitHub Apps** > *Add New*. Pick *Any Account* when choosing where to install the app. You will need to *Request* installation to any organization you are a member of, which an administrator must approve.

1. On the Organization's settings page, click **Developer Settings** > **GitHub Apps** > *Add New*
2. Fill out the following fields:
   * *GitHub App name* must be unique (e.g. `YourOrg-Veza-Integration-01`)
   * *Homepage URL* is not used but required by GitHub. Enter an address such as the URL of your Veza instance (e.g. `https://yourorg.vezacloud.com`)
   * All other fields are optional
3. Assign the required permissions to the application. Add the following `Read-Only` permissions:
   * `Repository permissions - Administration`
   * `Repository permissions - Metadata`
   * `Repository permissions - Repository security advisories`
   * `Organization permissions - Custom repository roles`
     * Support for Custom Repository Roles is only available for GitHub Enterprise Cloud environments.
   * `Organization permissions - Members`
   * `Organization permissions - Administration`
   * `Organization permissions - Personal Access Tokens`
   * `Enterprise permissions - Custom enterprise roles`
     * Required for discovering enterprise-level custom roles and role assignments. Only available for GitHub Enterprise Cloud environments.
4. Enter *Only on this account* for *Where can this app be installed?*, or enable the app for other accounts by making it Public.
5. Click *Create GitHub App* to open the app settings page
   * Note the “App ID” towards the top of the screen. Click *Generate a private key* to download the base64-encoded .pem key file.
6. Finally, install the App into the Organization(s) you want to discover:
   1. Open the app settings page (**Settings** > **Developer settings** > **GitHub Apps** > `your-application`)
   2. Click *Install* next to the organization name
   3. Unless you want to exclude specific resources, pick *All Repositories*
   4. Click *Install* and approve the permissions

#### Discovering user email addresses

Github only publishes user emails that belong to a verified or approved domain for the tenant organization. This intentional behavior allows personal accounts to serve as individual developer portfolios that are portable across companies. To filter users by email or configure identity mappings, you will need to ensure that users in your organization have addresses that match a verified/approved domain.

An organization owner must configure verified/approved domains for GitHub. If such a domain already exists, you should request that all users add an email address belonging to the domain. For more information see the [Verifying or Approving a Domain for your Organization](https://docs.github.com/en/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)

### Veza setup instructions

To add a GitHub integration, use the navigation bar to open the **Integrations** page. Click *Add New Integration* and enter the required information using the App Key and ID from the earlier steps.

| Field                                 | Notes                                                                                                                                                      |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                                  | Name to identify the configuration                                                                                                                         |
| App ID                                | GitHub App ID                                                                                                                                              |
| App Key                               | GitHub App private key                                                                                                                                     |
| Insight Point                         | Leave default or use an external [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md)                                         |
| Server URL                            | For self-managed or privately hosted GitHub Enterprise, the custom server URL (e.g., `https://github.yourcompany.com`). Leave empty for public GitHub.com. |
| Enterprise Cloud Slug                 | For GitHub Enterprise cloud deployments, the Enterprise ID as in `https://github.com/enterprises/<ENTERPRISE-SLUG>`                                        |
| Collect personal access tokens        | Enable to show GitHub Personal Access Tokens in the Veza Access Graph                                                                                      |
| Ignore expired personal access tokens | Enable to exclude expired PATs during extraction.                                                                                                          |
| Enable Usage for Lifecycle Management | Toggle to enable [Lifecycle Management](/4yItIzMvkpAvMVFAamTf/integrations/integrations/github/provisioning.md) capabilities                               |

* The `Enterprise cloud slug` is optional. When provided, the ID is used to correlate external identities with GitHub users.
* Leave `Server URL` empty only when connecting to public GitHub.com (github.com). For self-managed GitHub Enterprise Server or privately hosted GitHub Enterprise Cloud instances with custom domains, provide the full server URL (e.g., `https://github.yourcompany.com`).

> Veza uses the app credentials for the initial connection. Future requests use an access token, which the connector will generate at runtime.

## Notes and supported entities

After enabling the integration and connecting to GitHub, Veza will discover entities and attributes for:

* GitHub Organizations
* GitHub Personal Accounts (individual user accounts within organizations)
* GitHub Personal Access Tokens
* GitHub Teams
* GitHub Roles
* GitHub Enterprise Roles
* GitHub Apps
* GitHub Repositories

**Cross-Service Connections:** Veza automatically detects relationships between Okta and Azure AD identities and GitHub user accounts. If your organization implements Single-Sign On (SSO) for another Identity Provider (IdP), you can add [Custom Identity Mappings](/4yItIzMvkpAvMVFAamTf/integrations/configuration/custom-identity-mappings.md) to correlate GitHub Personal Accounts with identities from any integrated IdP.

> Use the [Access Intelligence Overview](/4yItIzMvkpAvMVFAamTf/features/insights/entities-overview.md) to review all entities Veza has discovered.

Veza uses some common properties for all GitHub entities:

| Property     | Notes                                     |
| ------------ | ----------------------------------------- |
| DatasourceID | Veza unique ID for the GitHub data source |
| ID           | Veza global unique identifier             |
| Name         | Veza display name                         |
| CreatedAt    | Creation date (within GitHub)             |
| UpdatedAt    | Updated date (within GitHub)              |

### GitHub Organization

Organizations are shared accounts where teams of users can work together on public and private projects.

| Property          | Notes                                                                 |
| ----------------- | --------------------------------------------------------------------- |
| PublicRepos       | Number of public repositories                                         |
| TotalPrivateRepos | Number of private repositories                                        |
| OwnedPrivateRepos | Number of owned repositories                                          |
| Is2faEnabled      | True if the organization account requires multi-factor authentication |
| Plan              | Organization Payment plan type                                        |

### GitHub Personal Account

A personal account (GitHub User) can be a member of the organization or an "outside collaborator" (who has some permissions on repositories, but is not an org member).

| Property         | Notes                                                             |
| ---------------- | ----------------------------------------------------------------- |
| DisplayName      | GitHub username                                                   |
| Is2faEnabled     | Whether the user has enabled MFA                                  |
| PublicEmail      | Email address used for commits (if set)                           |
| Emails           | List of all user emails matching verified domain                  |
| LdapDn           | Distinguished Name (DN) the user maps to (GitHub Enterprise only) |
| FullAdmin        | True if the user is Site Admin                                    |
| UserType         | GitHub users are classified as "Human" identities                 |
| IdentityUniqueID | GitHub LoginName                                                  |

You can *explain effective permissions* to show the grouped role permissions assigned to the user.

### GitHub Personal Access Token

A Personal Access Token (PAT) is a credential used to authenticate GitHub API requests. It can be either a classic token or a fine-grained token with specific permissions.

| Property                | Notes                                                        |
| ----------------------- | ------------------------------------------------------------ |
| AccessAllRepositories   | True if token has access to all repos in the organization    |
| CanExpire               | Whether the token has an expiration date                     |
| Classic                 | True if this is a classic PAT (vs fine-grained)              |
| CreatedAt               | Timestamp when the token was created                         |
| ExpiresAt               | Expiration timestamp (if set)                                |
| IsActive                | Whether the token is currently active                        |
| LastUsedAt              | Last time the token was used to authenticate                 |
| OwnerLogin              | GitHub username of the token owner                           |
| Repositories            | List of specific repositories the token can access           |
| Scopes                  | List of OAuth scopes (for classic tokens)                    |
| RepositoryPermissions   | List of repository-level permissions (fine-grained tokens)   |
| OrganizationPermissions | List of organization-level permissions (fine-grained tokens) |

Token can be connected to a Github Personal Access Token Permission node representing the effective permissions on GitHub resources.

### GitHub Team

Teams represent groups of users. Assigning GitHub Personal Accounts to teams grants the users permissions on the team's repositories.

| Property   | Notes                                                                      |
| ---------- | -------------------------------------------------------------------------- |
| ParentTeam | The team in your organization's hierarchy under which this group is nested |
| LdapDn     | Distinguished Name (DN) the team maps to (GitHub Enterprise only)          |

> Possible roles on repositories are: admin, maintain, push, triage, pull.

### GitHub App

Apps on GitHub (Non-human service accounts) enable automation, workflows, and integrations for a user or organization. GitHub App permissions are not assigned with roles, but are individually granted, for example `"administration":"read"`,`"emails":"read"`,`"metadata":"read"`,`"members":"read"`,`"organization_administration":"read"`.

| Property    | Notes                                   |
| ----------- | --------------------------------------- |
| Permissions | List of permissions assigned to the app |

### GitHub Repository

| Property         | Notes                          |
| ---------------- | ------------------------------ |
| IsArchived       | True if repository is archived |
| IsDisabled       | True if repository is disabled |
| IsFork           | True if repository is a fork   |
| ForkCount        | Number of repository forks     |
| GithubInternalID | Repository `ID`                |

#### Custom properties

GitHub Organizations can define custom properties, which Veza can gather as searchable attributes on GitHub Repository entities. Custom properties have the following behavior:

* Custom properties are defined at the organization level but are only assignable to repositories within that organization.
* All repositories in an organization share the same set of custom property definitions.
* Property keys must be unique within each organization but can be reused across different organizations.

Custom properties appear in Veza using the format `organizationName.propertyName`. For example, a property named `environment` in an organization named `acme-corp` is represented as `acme-corp.environment` in Veza. The display name uses title case with spaces: "Acme Corp Environment".

**Custom properties are not gathered by default**. To gather custom properties, use the **Custom Organization Properties** section in the GitHub integration configuration:

1. Click **Add Custom Property**.
2. Enter the property name in the **Name** field using the format `organizationName.propertyName`.
3. Select the data type from the **Type** dropdown: String, Number, Boolean, Timestamp, Timestamp (Windows AD Format), or String List.
4. Repeat for each property to gather.

Only properties listed in the configuration are gathered. If a property exists in GitHub but is not listed, Veza ignores it.

### GitHub Role

These roles grant a set of repository permissions to teams or individual users. Roles can also apply to an organization or team.

| Property    | Notes                                   |
| ----------- | --------------------------------------- |
| Permissions | list of permissions granted by the role |

### GitHub Enterprise Role

Enterprise roles are custom roles defined at the GitHub Enterprise level that grant permissions across the enterprise. Veza discovers enterprise roles and their assignments to users and teams.

| Property    | Notes                                               |
| ----------- | --------------------------------------------------- |
| Name        | Display name of the enterprise role                 |
| Description | Description of the role's purpose                   |
| Permissions | List of permissions granted by the role             |
| Source      | Origin of the role (e.g., `enterprise` or `preset`) |
| CreatedAt   | Timestamp when the role was created                 |
| UpdatedAt   | Timestamp when the role was last modified           |

Enterprise roles require the `Enterprise permissions - Custom enterprise roles` permission on the GitHub App and are only available for GitHub Enterprise Cloud environments.


---

# Agent Instructions: 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.veza.com/4yItIzMvkpAvMVFAamTf/integrations/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.