> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipefort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub setup

> Connect Pipefort to a GitHub account or organization.

Pipefort talks to GitHub through two surfaces. **You only interact with one of them** — the GitHub App that grants repo read access. The login OAuth is invisible: click "Sign in with GitHub", approve once, done.

<Note>
  This page is for **users** of a Pipefort deployment. If you're standing up your
  own deployment and need to register the GitHub App itself, see
  [Create your GitHub App](/webapp/create-github-app).
</Note>

## 1. Sign in

Open your Pipefort dashboard and click **Sign in with GitHub**. Identity is established via GitHub OAuth. Pipefort receives only your username and avatar — no repo access yet.

## 2. Install the GitHub App

After signing in, the dashboard prompts you to **Connect**. This opens GitHub's app-install flow for the **Pipefort** GitHub App.

You choose:

* **Account or organization.** Install on your personal account, or on any org you have admin rights to.
* **All repositories** or a **specific selection**. Pipefort scans only the repos the App is installed on.

The App requests these permissions:

| Permission                   | Scope            | Why                                                                                                                                                 |
| ---------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Metadata**                 | Read-only        | Mandatory for any GitHub App.                                                                                                                       |
| **Contents**                 | Read **+ Write** | Read `.github/workflows/*.yml` to scan. Write is used only by the **Open fix PR** button to commit the fixed YAML to a new branch.                  |
| **Workflows**                | Write            | Also required by **Open fix PR** — GitHub blocks commits to `.github/workflows/*` unless the App holds this scope on top of Contents.               |
| **Pull requests**            | Write            | Used only by **Open fix PR** to open (and reuse) the pull request.                                                                                  |
| **Administration / Actions** | Read **+ Write** | Read branch-protection and Actions policy to scan; write is used only by the per-finding **Auto-fix** button for repository-configuration findings. |

<Note>
  Scanning is entirely read-only. The **write** scopes are used **only** when *you* click **Auto-fix** or **Open fix PR** on a finding — Pipefort never pushes commits, opens PRs, or changes settings on its own. Nothing lands on your default branch without a PR you merge. Prefer to grant nothing extra? Set the write rows to Read-only at install time; scanning still works and the fix buttons simply stay hidden. See [GitHub App permissions](/concepts/github-app-permissions) for the full breakdown.
</Note>

After you approve, GitHub redirects back to the dashboard's `/connect/callback`, which links the installation to your signed-in account. You'll see the connected installation appear on the dashboard.

## 3. Connect more accounts (optional)

Click **Connect** again to install the App on another account or org. Pipefort aggregates posture across every installation linked to your user.

## Verify it works

<Steps>
  <Step title="Repos appear">
    The **Repositories** page lists every repo the App can read.
  </Step>

  <Step title="Scan runs">
    Click **Scan all** on the dashboard. You should see live progress, the severity donut populate, and the trend chart fill in.
  </Step>

  <Step title="Findings deep-link">
    Open a repo's detail page. Each finding's `file:line` link should jump to the exact location on GitHub's default branch.
  </Step>
</Steps>

## Revoking access

To remove Pipefort from a repo or organization, uninstall the GitHub App from GitHub itself:

* **Personal account:** [https://github.com/settings/installations](https://github.com/settings/installations)
* **Organization:** `https://github.com/organizations/<org>/settings/installations`

Uninstalling removes the App's token immediately. Historical scan data in Pipefort persists until you delete it from the dashboard.