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

# sdlc.yaml

> How sdlc.yaml configures your release pipeline and propagates changes through LaneSync and GitHub.

**`sdlc.yaml`** is the single source of truth for each repository's SDLC policy. LaneSync reads it from GitHub — never hardcode check names or workflow names in application code.

## File location

```
your-repo/
  sdlc.yaml          ← repo root
  .github/workflows/
```

LaneSync bootstraps this file during the repo setup wizard. You edit it like any other config — commit, push, and LaneSync reacts via webhook.

## Minimal example

<Snippet file="snippets/sdlc-yaml-example.mdx" />

## Schema overview

| Top-level key | Purpose                                     |
| ------------- | ------------------------------------------- |
| `version`     | Config schema version (currently `v1`)      |
| `name`        | Display name for the repository in LaneSync |
| `stages`      | Per-stage gate configuration                |
| `features`    | Optional test-to-feature mapping patterns   |

See the full [sdlc.yaml schema reference](/reference/sdlc-yaml-schema).

## Live reads vs database cache

LaneSync maintains two views of your config:

| Consumer                                    | Source                 | Freshness                |
| ------------------------------------------- | ---------------------- | ------------------------ |
| `GET /api/milestones/:id/stage-details`     | **Live from GitHub**   | 60s cache TTL            |
| Sync engine, rulesets, DB `required_checks` | Parsed on webhook push | May lag until push fires |

<Warning>
  The database `required_checks` column is a **cache**. When you rename a CI job, update `sdlc.yaml` and push — the webhook re-parses checks, updates the DB, re-applies rulesets, and re-syncs milestones atomically.
</Warning>

## Propagation on push

When `sdlc.yaml` is pushed to the default branch:

```mermaid theme={null}
sequenceDiagram
  participant GH as GitHub
  participant WH as Webhook handler
  participant DB as PostgreSQL
  participant RS as GitHub Rulesets
  participant Sync as Sync engine

  GH->>WH: push event (sdlc.yaml changed)
  WH->>WH: parseRequiredChecks()
  WH->>DB: updateRepoSdlcConfig()
  WH->>RS: ensureRulesets()
  WH->>Sync: syncRepo()
  WH->>WH: invalidate stage-details cache
```

All four steps must happen together. If you add a new consumer of `required_checks`, wire it into `handleSdlcYamlChange` in the webhook handler.

## Required checks naming

Check names in `required_checks` must match **GitHub Actions job names** (the `name:` field or job key) exactly:

```yaml theme={null}
development:
  required_checks:
    - CI — Build & Test    # ← must match workflow job name
```

LaneSync never falls back to project-specific default check names. The only infrastructure constant is **`SDLC Enforce`**.

## Trunk-based vs release-branch

<Tabs>
  <Tab title="Release-branch (default)">
    ```yaml theme={null}
    development:
      branch: main
    testing:
      branch_pattern: "release/*"
    ```

    Cut `release/v1.0.0` after development completes. Testing gates evaluate checks on the release branch.
  </Tab>

  <Tab title="Trunk-based">
    Configure during the repo setup wizard to promote from `main` without a release branch.

    Testing gates evaluate checks on the trunk branch directly.
  </Tab>
</Tabs>

## Feature mapping (optional)

Link test files to external feature IDs for quality tracking:

```yaml theme={null}
features:
  - pattern: "src/__tests__/auth*"
    system: github
    external_id: "42"
```

See [Quality tracking](/concepts/quality-tracking).