> ## 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.

# Trusted Bootstrap

> Set up LaneSync on the minimal GitHub App tier using a Personal Access Token — review every file before merge.

Trusted Bootstrap is the setup path for the **minimal GitHub App tier** (LaneSync Lite). Your organization keeps tight control: the App never receives `administration:write` or `workflows:write`, and you merge bootstrap changes yourself using a Personal Access Token (PAT).

## When Trusted Bootstrap is used

Trusted Bootstrap applies when:

* You installed the **minimal tier** GitHub App (`administration:read` only — no ruleset auto-creation by the App)
* Your org policy blocks Apps from writing workflow files or branch protection settings
* Zero-touch bootstrap is unavailable (for example, the full tier App lacks required permissions)

<Tabs>
  <Tab title="Full tier (zero-touch)">
    The App creates workflows and rulesets directly. Bootstrap completes in one step — see [Install the GitHub App](/guides/install-github-app).
  </Tab>

  <Tab title="Minimal tier (trusted)">
    You supply a PAT. LaneSync opens a **`sdlc-bootstrap`** PR with all files for your review. After merge, branch protection is configured **automatically** using your encrypted token — no GitHub Actions step required.
  </Tab>
</Tabs>

## Before you start

* LaneSync GitHub App installed on the repository ([Install the GitHub App](/guides/install-github-app))
* Repo setup wizard completed through branches, language, CI checks, and approvals
* A GitHub **Personal Access Token** with:
  * **`repo`** scope (classic PAT) or repository **Contents: Read and write** + **Administration: Write** (fine-grained PAT)
  * **`workflow`** scope (classic PAT) or **Actions: Read and write** (fine-grained PAT)
* At least one commit on the repository (empty repos cannot bootstrap)

<Tip>
  Generate a classic PAT at **GitHub → Settings → Developer settings → Personal access tokens**. Fine-grained tokens must explicitly include this repository.
</Tip>

## Bootstrap flow

```mermaid theme={null}
stateDiagram-v2
  [*] --> NOT_STARTED
  NOT_STARTED --> PR_CREATED: POST bootstrap-pr
  PR_CREATED --> SETUP_PENDING: Merge sdlc-bootstrap PR
  SETUP_PENDING --> COMPLETE: Auto rulesets via stored PAT
  COMPLETE --> [*]
```

<Steps>
  <Step title="Complete the repo wizard">
    In [lanesync.dev](https://lanesync.dev), open the repository setup wizard. Configure development branch, language, CI check names, staging toggle, and release model. LaneSync saves your choices before bootstrap begins.
  </Step>

  <Step title="Create the bootstrap PR">
    On the final **Set up** step, paste your PAT and click **Create bootstrap PR**.

    LaneSync calls `POST /api/repos/:repoId/bootstrap-pr` using your token and opens a PR from the `sdlc-bootstrap` branch. The PR includes:

    * `sdlc.yaml` at the repo root
    * `.github/workflows/sdlc-enforce.yml` — SDLC gate (always required)
    * `.github/workflows/ci.yml` (or a language-specific CI template) — evidence uploader

    Your PAT is stored **encrypted** for up to 1 hour so LaneSync can configure branch protection after you merge. It is wiped after use.

    Bootstrap state moves to **`PR_CREATED`**.
  </Step>

  <Step title="Review and merge the PR">
    Open the PR link from the wizard or your GitHub pull requests list. Review every added file — nothing is auto-merged.

    When you are satisfied, merge the PR. LaneSync detects the merge via webhook, applies branch protection rulesets with your token, and marks the repository **`COMPLETE`**.
  </Step>

  <Step title="Wait for setup to complete">
    The setup wizard shows **Configuring branch protection…** while LaneSync applies rulesets. This usually completes within a few seconds — no GitHub Actions step is required.

    If setup stays pending, use **Retry branch protection setup** in the wizard and paste your PAT again.
  </Step>
</Steps>

<Note>
  `SDLC Enforce` is always a required check — it is LaneSync infrastructure, not something you add to `sdlc.yaml`. Your wizard-configured CI job names must match GitHub Actions job names exactly.
</Note>

## File integrity monitoring

LaneSync monitors **watched workflow files** (`WATCHED_FILES`) on every push webhook:

| Watched file                         | Purpose                       |
| ------------------------------------ | ----------------------------- |
| `.github/workflows/sdlc-enforce.yml` | Posts SDLC gate status checks |
| `.github/workflows/ci.yml`           | Uploads evidence artifacts    |

If a watched file is **modified** or **deleted**:

1. LaneSync sets a file integrity flag on the repository
2. A GitHub issue is opened in your repo (label: `sdlc-integrity`) naming the affected files and pusher
3. Pipeline enforcement may stop working until files are restored

**To restore:** open the LaneSync dashboard for the repository and click **Restore workflow files**. LaneSync creates a new PR using your PAT — review and merge it to clear the integrity flag.

Restoring a previously deleted watched file automatically clears the breach flag.

<Warning>
  Do not delete `sdlc-enforce.yml` or your CI evidence workflow unless you intend to disable LaneSync enforcement. Tampering triggers an integrity alert, not silent degradation.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bootstrap PR creation fails with 403">
    Regenerate your PAT with `repo` and `workflow` scopes. For fine-grained tokens, grant **Contents** and **Actions** write access to this repository only.
  </Accordion>

  <Accordion title="Branch not found during bootstrap">
    The development branch you entered in the wizard must exist on GitHub. Return to the **Branches** step and match GitHub's default branch name.
  </Accordion>

  <Accordion title="Stuck at SETUP_PENDING">
    Open the repo setup wizard and click **Retry branch protection setup**. Ensure your PAT has **repo** + **Administration (write)** access (classic) or **Contents** + **Actions** + **Administration** (fine-grained). Tokens expire after 1 hour — generate a fresh one if needed.
  </Accordion>

  <Accordion title="HTTP 402 when starting bootstrap">
    Your workspace hit the free-plan repository limit. See [Billing and plans](/guides/billing-and-plans) to upgrade to Pro.
  </Accordion>

  <Accordion title="Rulesets missing after COMPLETE">
    Use **Retry branch protection setup** in the setup wizard. On minimal tier, rulesets are created by LaneSync using your PAT — not by the App directly. Contact support if rulesets were deleted manually after setup.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Install the GitHub App" icon="github" href="/guides/install-github-app">
    Full vs minimal tier permissions and installation steps.
  </Card>

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