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.
.levelfour/config.yml.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.aias 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.
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 Infrastructure-as-Code (.tf, CloudFormation, CDK and Pulumi sources, Kubernetes manifests) 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 |
Tuning the bot
Commit a .levelfour/config.yml at the root of a repository's default branch. 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
- PR bot configuration is the
.levelfour/config.ymlschema - Integrations lists the other tools you can connect