GitHub

GitHub Integration Guide

Introduction

GitHub is a web-based platform for version control and collaboration that allows individuals and teams to store, manage, and share their code and projects. It offers a wide range of features such as issue tracking, pull requests, code review, continuous integration, and more. This guide will walk you through the steps required to integrate GitHub with Perimeters.

Available Features

• Misconfiguration Rules

• Identity Rules

• User Inventory

Prerequisites

A GitHub account user with the following required privileges, else you can use the organization owner account and an API Token (Personal Access Token - Classic) with the listed required privileges.

Follow these steps to create API Token (Personal Access Token Classic):

1. Login using the account that was assigned the required scopes

2. Go to https://github.com/settings/apps

3. Expand Personal Access Tokens and select Tokens(classic)

4. Expand Generate New Token and select Generate new token(Classic)

5. Add "Perimeters Integration" in Note section or any other thing deemed suitable as purpose of the token.

6. Set the expiration to "No expiration"

7. Select these scopes :

   1. admin:enterprise

   2. admin:org

   3. public_repo

   4. read:project

   5. repo:status

   6. security_events

   7. user

   8. read:audit_log

8. Click "Generate Token" and copy the token.

Note: Be sure to have copied the token as it wont be accessible later.

Required Privileges

Scope	Use
repo	Access repositories [Meta Data]
admin:org	Read orgs, teams and org projects
user	Read All user data
admin:enterprise	Read enterprises
audit_log	Read audit log
read:project	Read projects [Meta Data]

Onboarding GitHub in your Perimeters account

Log in to your Perimeters account and navigate to the "Integrations" section. Select "GitHub" from the list of available integrations and click on “Add Application”

1. "Alias" - Provide a descriptive name for the integration (e.g. "My GitHub Integration").

2. "Namespace" - Organization Name - Copy the organization name from the URL and paste it in the input field. (e.g. https://github.com/organizations/perimeters/settings/profile, so you'll add perimeters)

3. "Email" - Provide the privileged user's email address.

4. "API Token" - Provide the API Token of the privileged user.

5. Click "Connect" to complete the onboarding process.

Once you have completed these steps, GitHub should be successfully integrated with your Perimeters account.