What is GitHub? #
GitHub is a cloud-based platform that allows developers to store, track, and collaborate on software projects. GitHub is based on Git, an open-source version control tool that allows multiple people to make changes to source files at the same time.
Why Should You Use the GitHub Connector? #
The GitHub connector provides visibility into the users and repositories in your environment. You can use this visibility to:
- ensure assets are managed per your security policies
- derive relationships between assets, users, applications, and data
How Does This Connector Work? #
Meridian executes read-only requests to the GitHub REST API and ingests only meta-data about ??? devices. Meridian does not retrieve any data stored on your assets.
Configuring the Connector in Meridian #
| Field |
Description |
Example |
|---|---|---|
|
Profile Name |
Name of this profile for the connector | production servers |
|
URL |
The URL for the GitHub API. |
https://api.github.com |
|
API Token (legacy) |
Specify the personal access token that has read access. For details see: :https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic. In step 8, add the following permissions
To use a personal access token with an organization that uses SAML single sign-on (SSO), you must first authorize the token. For details, see Authorizing a personal access token for use with SAML single sign-on – GitHub Enterprise Cloud Docs . |
p7g444S3IZ5wmFvmzWmx14qACXdzQ25b |
| Organization (legacy) |
The organization for the GitHub account, for example, MeridianInc. To find your organization, log in to Github. In the upper-right corner, select your profile photo, then click Your organizations. |
|
| App ID | The Application ID for the application you created in GitHub. This application allows Meridian to communicate with GitHub | |
| App Key File | PEM key for the new application. |
Source Documentation #
There are two ways to authenticate with GitHub. Both options are described below.
Creating an Application, App ID, and PEM Key for Meridian (Recommended) #
Before configuring the GitHub connector in Meridian, you must first create an application in GitHub. The application allows Meridian to securely communicate with GitHub.
For details on creating an application in GitHub, see https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.
To find the App ID and the PEM key for the new application, see https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/quickstart#get-your-app-credentials-and-identifying-information.
Permissions for Application #
When creating the application, assign the following required permissions:
- Administration. Read-only
- Code scanning alerts. Read-only
- Contents. Read-only
- Dependabot alerts. Read-only
- Metadata. Read-only
- Packages. Read-only
- Secret scanning alerts. Read-only
Creating an API Token for GitHub (Legacy) #
Before configuring the GitHub connector in Meridian, you must first create an API Token. The Meridian connector uses the API token to access the GitHub API.
-
From GitHub, Go to Settings -> Developer Settings -> Personal access token.
-
Generate a new token and then give the following read-only permissions:
-
read:packages
-
read:org
-
read:public_key
-
read:user
-
user:email
-
read:enterprise
-
-
To use a personal access token with an organization that uses SAML single sign-on (SSO), you must first authorize the token. For details, https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on.
-
To get the GitHub user email, the users must set their email addresses as “public”. In the user profile, select a primary email address to be “public”. If you do not set a public email address, then it will have a value of null.
