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

# Enforcement

> How LaneSync enforces SDLC gates at three layers — GitHub Rulesets, backend state machine, and the SDLC Enforce CI action.

LaneSync enforcement is **technical**, not procedural. Teams cannot skip stages by convention — the pipeline blocks merges and deploys when gates fail.

## Three layers

```mermaid theme={null}
flowchart TB
  dev[Developer opens PR]
  rulesets[GitHub Rulesets]
  enforce[SDLC Enforce check]
  merge[Merge allowed?]
  sync[LaneSync sync]
  stage[Stage computed]
  deploy[Deploy gate]

  dev --> rulesets
  dev --> enforce
  rulesets --> merge
  enforce --> merge
  merge --> sync
  sync --> stage
  stage --> deploy
```

| Layer                             | Mechanism                                   | What it blocks                                                            |
| --------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| **1. GitHub Rulesets**            | Branch protection on `main` and `release/*` | Merge without PR approval, missing required checks, force-push            |
| **2. Backend state machine**      | Sequential gate evaluation                  | Deploy promotion when prior stages incomplete                             |
| **3. CI Action (`sdlc-enforce`)** | GitHub status check `SDLC Enforce`          | PRs that violate SDLC policy (wrong branch, missing milestone link, etc.) |

## Layer 1 — GitHub Rulesets

When you bootstrap a repository (full-tier GitHub App), LaneSync creates rulesets that:

* Require pull request reviews before merging
* Require status checks including **`SDLC Enforce`** and checks from `sdlc.yaml` `required_checks`
* Block force-push and deletion on protected branches

Rulesets are **re-applied** when `sdlc.yaml` changes. The propagation chain:

```
push webhook → parseRequiredChecks()
  → updateRepoSdlcConfig() (DB required_checks)
  → ensureRulesets() (GitHub branch protection)
  → syncRepo() (re-evaluate milestone stages)
  → cache invalidation (stage-details TTL cleared)
```

<Note>
  `SDLC Enforce` is always a required check — it is LaneSync's own status check, not a user-configured workflow name.
</Note>

## Layer 2 — Backend state machine

The state machine in the LaneSync backend:

* Computes `current_stage` from GitHub data (issues, PRs, workflow runs, evidence)
* Marks individual gate items as `blocking` in stage details
* Exposes deploy readiness via `/api/milestones/check` (CI auth required: OIDC or API key)

**Key invariant:** A milestone in DEVELOPMENT only shows a check as blocking if that check name appears in `required_checks` (from live `sdlc.yaml`) **and** the workflow conclusion is `failure`.

Stage details are fetched live from GitHub on every request to `GET /api/milestones/:id/stage-details` (60-second cache TTL). Do not substitute DB reads for the live file — the DB cache may lag until the webhook fires.

## Layer 3 — SDLC Enforce CI action

Bootstrapped repos include a GitHub Actions workflow that runs the **`sdlc-enforce`** action. It posts a commit status named **`SDLC Enforce`** and fails when:

* PR targets a protected branch without meeting SDLC requirements
* Milestone linkage or stage rules are violated

See [SDLC Enforce action reference](/reference/sdlc-enforce-action) for behavior details.

## Enforcement vs visibility

| Capability                    | Enforcement                          | Visibility only |
| ----------------------------- | ------------------------------------ | --------------- |
| Block merge without CI        | Yes (Rulesets)                       | —               |
| Block merge on SDLC violation | Yes (`SDLC Enforce`)                 | —               |
| Block production deploy       | Yes (deploy gate + manual promotion) | —               |
| Show stage on dashboard       | —                                    | Yes             |
| Audit trail of transitions    | —                                    | Yes (recorded)  |

## Troubleshooting enforcement

<AccordionGroup>
  <Accordion title="Rulesets not created">
    The GitHub App needs **Administration: Read & Write** (full tier). Re-approve permissions on the installation.
  </Accordion>

  <Accordion title="Phantom BLOCKING badges">
    Usually caused by stale check names. Ensure `required_checks` in `sdlc.yaml` matches your GitHub Actions job names exactly, then push the file to trigger re-sync.
  </Accordion>

  <Accordion title="SDLC Enforce always failing">
    Verify the repo completed bootstrap and the workflow template was pushed. Check workflow run logs on the PR branch.
  </Accordion>
</AccordionGroup>