# GitHub

## 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
* Shadow Application Inventory
* Shadow Application Rules

## 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.

<details>

<summary>Follow these steps to create API Token (Personal Access Token Classic):</summary>

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.

</details>

## 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").&#x20;
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.

<br>


---

# 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://support.perimeters.io/perimeters-documentation/connecting-perimeters/integrations-for-security-insights/saas-applications/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.