# GitHub

> Install LevelFour as a GitHub App on your organization. One install covers both the PR bot and the savings pull requests LevelFour opens.

Source: https://docs.levelfour.ai/integrations/github


LevelFour installs as a single GitHub App on the organizations and repositories you select. One install covers both GitHub-side products: the bot that comments cost impact on the pull requests your team opens, and the savings pull requests LevelFour opens against your default branch.

> **Note**
>
> Granting access to a repository opts it into both, and the bot is on by default. Per-repo overrides live in [`.levelfour/config.yml`](/guides/pr-bot-configuration).

## Prerequisites

* You are an **Owner** of the GitHub organization. Members and outside collaborators cannot install third-party apps.
* Your organization does not block third-party GitHub Apps under **Settings > Third-party access**. Most organizations leave this open.
* You are signed in to `https://dashboard.levelfour.ai` as a member of the LevelFour organization you are connecting to.

## Install

### Open Settings, then Integrations

In the dashboard sidebar, click **Settings**, then **Integrations**, then the **GitHub** tile.

If the tile reads **Contact sales**, the GitHub products are not enabled for your organization yet. Click it to ask.

### Install the GitHub App

Click **Install GitHub App**. A new tab opens GitHub's install page.

GitHub asks two questions. **Which account** to install on: pick the organization you intend to connect. If the picker shows only your personal account, you are not an Owner, or the organization restricts third-party apps.

**Which repositories** to grant. **All repositories** covers every repo now and any added later. **Only select repositories** covers the ones you pick, which suits a phased rollout.

Click **Install**. GitHub returns you to LevelFour, and you can close that tab once it says you can.

### Wait for the panel to flip to Connected

The dashboard tab polls for the installation, moving through `Waiting for install` and `Verifying installation`.

> **Success**
>
> The pill lands on `Connected` within about ten seconds, and the installation appears with its repository count.

Comments on new pull requests start right away. The first pass over your existing Infrastructure-as-Code takes a few minutes.

## What the GitHub App grants

| Permission                         | Why we ask for it                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| Read repository metadata           | List the repositories you granted                                                      |
| Read and write repository contents | Read your Terraform files and CloudFormation templates, and open savings pull requests |
| Read issues                        | Correlate bot comments with related issues                                             |
| Read and write pull requests       | Comment cost impact, and update our own pull requests                                  |
| Read and write check runs          | Post a LevelFour status check in the PR's checks panel                                 |

> **Note**
>
> The app does not request admin scopes, secrets, environments, or actions configuration.

## Tuning the bot

Commit a `.levelfour/config.yml` at the root of a repository's default branch. [PR bot configuration](/guides/pr-bot-configuration) has the schema and the defaults.

## Changing or removing access

You change what LevelFour can see from inside GitHub. Open `https://github.com/organizations/<your-org>/settings/installations` and click **Configure** next to the LevelFour app. The dashboard's **Manage in GitHub** link goes straight there.

Adjust **Repository access** and save. GitHub notifies LevelFour immediately, and the dashboard shows the new count on the next page load.

To remove the app, click **Uninstall** at the bottom of the same page. LevelFour stops scanning within a minute. Comments and check runs already posted stay where they are.

## Troubleshooting

| Symptom                                             | What to do                                                                                                                                                        |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The install picker shows only your personal account | You are not an Owner, or the organization restricts third-party apps. Ask an Owner to install, or to lift the restriction under **Settings > Third-party access** |
| The dashboard is stuck on `Waiting for install`     | The popup was probably blocked. Click **Reopen GitHub install**. If GitHub returned a 404, contact support                                                        |
| `Verifying installation` lasts more than a minute   | Click **Cancel**, then **Install GitHub App** again. If it recurs, contact support with the `integration` query parameter from the URL                            |
| You uninstalled but the installation still shows    | Refresh after 30 seconds. If the row persists, contact support with the GitHub organization login                                                                 |

## Next

* [Pull request bot](/integrations/pull-request-bot) is what the bot posts and the commands it answers
* [PR bot configuration](/guides/pr-bot-configuration) is the `.levelfour/config.yml` schema
* [Integrations](/integrations) lists the other tools you can connect