GitHub

LevelFour installs as a single GitHub App on the organizations and repositories you select. One install powers both of our GitHub-side products:

• PR bot. Brings shift-left FinOps to your code review. On every pull request your team opens that touches Infrastructure-as-Code (Terraform, CloudFormation, AWS CDK, Pulumi, or Kubernetes manifests), the bot reads the diff, scores the cost and performance impact against your real LevelFour usage data (not a generic price book), posts a before vs after comparison comment in the PR conversation, drops inline "Suggested change" boxes on the diff with concrete commits to optimize cost or performance, and surfaces a check-run status visible in the PR's checks panel. The conversation about spend happens at review time, before the regrettable monthly bill arrives.
• IaC PR platform. Reads the Infrastructure-as-Code across the repos you granted access to (Terraform, CloudFormation, AWS CDK, Pulumi, and Kubernetes manifests), finds cost waste, and opens pull requests against your default branch with the savings changes ready for you to review and merge. Same engine, same customer data, same commit suggestions, but proactively driven by LevelFour rather than reactively on a PR you opened.

You get both products from the same install. There is no separate "PR bot" install or "IaC platform" install; granting access to a repo opts it in to both. The bot is on by default; per-repo overrides (silence the bot, drop inline suggestions, exclude paths) live in .levelfour/config.yml.

This is a self-service flow you complete from the LevelFour dashboard. No onboarding email loop, no credentials to share.

If you also want to onboard cloud accounts, see AWS single account or AWS multi-account.

Prerequisites

• You are an Owner of the GitHub organization you want to install on. Members and outside collaborators cannot install third-party apps.
• Your organization does not block third-party GitHub Apps under Settings -> Third-party access. Most orgs leave this open by default.
• You are signed in to the LevelFour dashboard at https://dashboard.levelfour.ai as a member of the LevelFour organization you want to connect this GitHub org to.

Step 1. Open Connect Accounts -> GitHub

In the dashboard sidebar, click Connect Accounts, then click the GitHub tile.

You land on https://dashboard.levelfour.ai/connect-accounts/github. The panel shows a short overview, three numbered steps, and an Install GitHub App button. If your org already has LevelFour installations, they appear in the Connected installations section at the top.

Step 2. Install the GitHub App

Click Install GitHub App. A new tab opens GitHub's install page for the LevelFour app.

GitHub asks two questions:

1. Which account do you want to install on. Pick the GitHub organization you intend to connect. If the picker only shows your personal account, you are not an Owner on the target org, or the org has third-party app restrictions enabled.
2. Which repositories to grant access to. Two options:
   • All repositories grants access to every repo in the org now and any repo added later. Use this when LevelFour should track everything.
   • Only select repositories grants access to the repos you pick. Use this for a phased rollout.

Click Install. GitHub redirects to a callback page on the LevelFour dashboard. You can close that tab once it shows "You can close this window."

Step 3. Wait for the panel to flip to Connected

The original /connect-accounts/github tab polls for the installation. The status pill cycles through Waiting for install and Verifying installation, and lands on Connected within five to ten seconds. The Connected installations list now shows your GitHub org with the repo count.

LevelFour starts reading repo metadata right away. Cost analysis on existing Infrastructure-as-Code (Terraform, CloudFormation, CDK, Pulumi, Kubernetes manifests) takes a few minutes; comments on new pull requests start immediately.

What the GitHub App grants

LevelFour requests these permissions:

• Read access to repository metadata so we can list the repos you granted us.
• Read and write access to repository contents so we can read your Infrastructure-as-Code files (.tf, .json/.yml CloudFormation, CDK and Pulumi sources, .yaml/.yml Kubernetes manifests) and propose savings via pull requests we open.
• Read access to issues so we can correlate bot comments with related issues.
• Read and write access to pull requests so we can comment cost impact on your PRs and update our own.
• Read and write access to check runs so we can post a "LevelFour" status check that's visible in the PR's checks panel.

The app does not request access to admin scopes, secrets, environments, or actions configuration.

Tuning the PR bot

Once installed, the PR bot is on by default for every repo you granted access to. You can adjust per-repo behavior by committing a .levelfour/config.yml file at the root of the repo's default branch. See PR bot configuration for the schema and examples.

A dashboard-driven org and per-repo toggle is on the roadmap for customers managing thousands of repos. See the "Coming soon" section of the configuration guide.

Adding or removing repositories later

You change which repositories LevelFour can see from inside GitHub, not the LevelFour dashboard:

1. Open https://github.com/organizations/<your-org>/settings/installations on GitHub.
2. Click Configure next to the LevelFour app.
3. Adjust the Repository access section. Save.

GitHub fires a webhook to LevelFour the moment you save. The dashboard reflects the new repo count on the next page load.

The dashboard's Manage in GitHub link next to each connected installation deep-links straight to this settings page.

Removing the GitHub App

To remove LevelFour from a GitHub organization:

1. Open https://github.com/organizations/<your-org>/settings/installations on GitHub.
2. Click Configure next to the LevelFour app.
3. Scroll to the bottom and click Uninstall.

GitHub fires the uninstall webhook to LevelFour. We delete the installation record and stop scanning your repos within a minute. Pull request comments and check runs LevelFour previously posted stay in place for your audit log.

Troubleshooting

The install picker only shows my personal account, not my org You are not an Owner of the GitHub organization, or the org restricts third-party apps. Ask an Owner to install for you, or ask them to lift the restriction in Settings -> Third-party access.

The dashboard is stuck on Waiting for install The popup may have been blocked. Click Reopen GitHub install to open the URL in a new tab manually. If GitHub returned a 404 on the install URL, contact LevelFour support: the GitHub App slug may have changed.

The dashboard shows Verifying installation for more than a minute GitHub redirected the popup but LevelFour could not validate the install. Click Cancel, then Install GitHub App again. If the issue recurs, contact LevelFour support with the integration ID from the URL (the ?integration= query parameter).

I uninstalled but the dashboard still shows the installation Refresh the page after waiting 30 seconds. If the row persists, contact LevelFour support with the GitHub org login.