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

# Install the GitHub App

> Install and configure the LaneSync GitHub App on your organization — full vs minimal tier and required permissions.

The LaneSync **GitHub App** connects your repositories to the hosted SaaS at [lanesync.dev](https://lanesync.dev). Installation triggers repository discovery, webhook subscription, and the repo setup wizard.

## Installation flow

<Steps>
  <Step title="Sign in to LaneSync">
    Go to [lanesync.dev](https://lanesync.dev) and authenticate with GitHub OAuth.
  </Step>

  <Step title="Start installation">
    From the setup wizard, click **Install GitHub App**. You are redirected to GitHub to select org/account and repositories.
  </Step>

  <Step title="Grant repository access">
    Choose **All repositories** or select specific repos. You can adjust access later in GitHub Settings → Applications. If you select no repositories, LaneSync creates your workspace but the dashboard stays empty until you grant access and sync — you do not need to re-install the App.
  </Step>

  <Step title="Approve permissions">
    Review the requested permissions and click **Install**. LaneSync receives an `installation` webhook and creates or links your tenant.
  </Step>

  <Step title="Complete repo setup">
    For each new repository, run the **repo setup wizard** to configure branches, CI checks, and bootstrap `sdlc.yaml` plus workflows.
  </Step>
</Steps>

## Wizard configuration

After installation, open the repo setup wizard for each repository. The wizard saves configuration before bootstrap runs.

| Field                                | Description                                                                                              |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| **Development branch** (`devBranch`) | Where day-to-day PRs land — often `main`, but may differ (e.g. `develop`)                                |
| **Default branch**                   | Repository default branch; used as the bootstrap PR base                                                 |
| **Language**                         | Selects the CI workflow template (`ci-node.yml`, `ci-python.yml`, etc.)                                  |
| **CI check names**                   | GitHub Actions job names for development and testing stages — must match workflow `name:` fields exactly |
| **`hasStaging` toggle**              | **On:** full Dev → Staging → Prod pipeline with staging evidence gates. **Off:** Dev → Prod only         |
| **Release model**                    | **Trunk:** test on the development branch. **Release-branch:** cut `release/*` branches for testing      |

Additional wizard steps cover existing CI/deploy workflows and PR approval counts. LaneSync posts your choices to `POST /api/repos/:repoId/config` before bootstrap.

<Tip>
  Example CI check names like `CI — Build & Test` are placeholders — use the exact job names from your repository's workflows.
</Tip>

## After install — two bootstrap paths

<Tabs>
  <Tab title="Full tier (zero-touch)">
    **Requires:** `administration:write` and `workflows:write` on the GitHub App.

    On the final wizard step, click **Set up automatically**. LaneSync calls `POST /api/repos/:repoId/bootstrap` using the App token, pushes files, creates rulesets, and marks the repository **`COMPLETE`** in one step.

    Best for teams that want hands-off branch protection and rulesets.
  </Tab>

  <Tab title="Minimal tier (trusted bootstrap)">
    **Requires:** `administration:read` only on the App; you supply a PAT with `repo` + `workflow` + **Administration** access (classic `repo` scope includes admin; fine-grained needs Administration: Write).

    LaneSync opens a **`sdlc-bootstrap`** PR for your review. You merge it; branch protection is configured **automatically** using your encrypted PAT. State progresses through `PR_CREATED` → `SETUP_PENDING` → **`COMPLETE`**.

    See the full walkthrough: [Trusted Bootstrap](/guides/trusted-bootstrap).
  </Tab>
</Tabs>

## Bootstrap state progression

```mermaid theme={null}
stateDiagram-v2
  direction LR
  [*] --> NOT_STARTED: Wizard saved
  NOT_STARTED --> COMPLETE: Full tier zero-touch
  NOT_STARTED --> PR_CREATED: Minimal tier PAT bootstrap
  PR_CREATED --> SETUP_PENDING: Merge bootstrap PR
  SETUP_PENDING --> COMPLETE: Auto rulesets via stored PAT
```

On minimal tier, LaneSync polls bootstrap status in the wizard until state reaches **`COMPLETE`**.

## App tiers

<Tabs>
  <Tab title="Full tier (recommended)">
    **Best for:** Teams that want zero-touch branch protection and rulesets.

    | Capability                              | Full tier |
    | --------------------------------------- | --------- |
    | Webhooks and sync                       | Yes       |
    | Bootstrap `sdlc.yaml` + CI              | Yes       |
    | Create GitHub Rulesets                  | Yes       |
    | Requires `Administration: Read & Write` | Yes       |
    | Requires `Workflows: Read & Write`      | Yes       |

    LaneSync can enforce PR approvals and required checks without manual branch protection setup.
  </Tab>

  <Tab title="Minimal tier">
    **Best for:** Orgs with restricted Admin permissions or custom branch protection.

    | Capability                           | Minimal tier                                                                       |
    | ------------------------------------ | ---------------------------------------------------------------------------------- |
    | Webhooks and sync                    | Yes                                                                                |
    | Bootstrap via PR (PAT)               | Yes                                                                                |
    | Auto-create rulesets                 | Yes — LaneSync applies them server-side after you merge (using your encrypted PAT) |
    | Requires `Administration: Read` only | Yes                                                                                |

    You review every bootstrap file before merge. See [Trusted Bootstrap](/guides/trusted-bootstrap).
  </Tab>
</Tabs>

## Required permissions

| Permission                     | Purpose                                                    |
| ------------------------------ | ---------------------------------------------------------- |
| **Metadata**                   | Repository discovery                                       |
| **Contents**                   | Read/write `sdlc.yaml` and workflow files during bootstrap |
| **Issues & Pull requests**     | Milestone and PR sync                                      |
| **Actions**                    | Workflow run status for gate evaluation                    |
| **Checks**                     | Status check integration                                   |
| **Statuses**                   | Post `SDLC Enforce` status checks                          |
| **Administration** (full tier) | Create and update rulesets                                 |
| **Workflows** (full tier)      | Push workflow files during zero-touch bootstrap            |

<Warning>
  If rulesets are not created after bootstrap, verify the app has **Administration: Read & Write** (full tier) or use **Retry branch protection setup** in the setup wizard (minimal tier).
</Warning>

## Adding repositories later

1. GitHub → **Settings** → **GitHub Apps** → LaneSync → **Configure**
2. Add repositories to the installation
3. LaneSync discovers new repos on the next sync or via **Discover repos** in the dashboard
4. Run the repo setup wizard for each new repository

## Manual GitHub App setup (advanced)

Enterprise and self-hosted customers may register their own GitHub App and provide credentials via environment variables (`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY_PATH`). See [Enterprise self-hosting](/enterprise/self-hosting).

For the hosted SaaS, use the setup wizard — manual setup is not required.

## Related

<CardGroup cols={2}>
  <Card title="Trusted Bootstrap" icon="shield-check" href="/guides/trusted-bootstrap">
    PAT-based setup for the minimal App tier.
  </Card>

  <Card title="Configure sdlc.yaml" icon="file-code" href="/guides/configure-sdlc-yaml">
    Customize gates after bootstrap.
  </Card>
</CardGroup>