GitHub

Configuring the Veza integration for GitHub

Overview

The GitHub Enterprise integration enables Veza to authenticate with organizations and discover users, repositories, teams, and other 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 Reports.

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 for Veza, and install it into the GitHub organizations to discover.

• adding the integration to Veza 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 and Making a GitHub App Public or Private.

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

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

Veza setup instructions

To add a GitHub integration, open Configuration -> Data Sources. Find the list of standalone data sources and click Add New. Use 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
Server URL	For Enterprise Server, the address of the GitHub Enterprise server
Enterprise Cloud Slug	For GitHub Enterprise cloud deployments, the Enterprise ID as in https://github.com/enterprises/<ENTERPRISE-SLUG>

• The Enterprise cloud slug is optional. When provided, the ID is used to correlate external identities with GitHub users.

• Leave Server URL empty when connecting to GitHub cloud.

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

• GitHub Teams

• GitHub 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 to correlate GitHub Personal Accounts with identities from any integrated IdP.

Use the Entity Catalog 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 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

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