Deploy attribution

Deploy attribution records the release boundary for a project. It connects graph changes, runtime behavior, and observations to the commit that shipped.

CI boundary

Upload deploys at the same point your team treats as production.

• Use one TrueClara project per environment.
• Use a non-shallow checkout so previous commits can be resolved.
• Keep TRUECLARA_PROJECT_KEY in CI secrets only.
• Run the parser against the exact app version being deployed.

Minimal workflow

name: trueclara-deploy

on:
  push:
    branches: [main]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @trueclara/parser . --pretty -o trueclara-graph.json
      - run: node scripts/post-trueclara-deploy.mjs
        env:
          TRUECLARA_PROJECT_KEY: ${{ secrets.TRUECLARA_PROJECT_KEY }}
          TRUECLARA_ENVIRONMENT: production

The public trueclara/deploy-action@v1 package is still in beta verification. Until it is public, post to the deploy API from a small script in your repo.

Payload

Post to POST /v1/deploys with X-Trueclara-Project-Key.

{
  "environment": "production",
  "commit_sha": "abc1234def5678",
  "previous_commit_sha": "9fe8123abcd4567",
  "branch": "main",
  "pr_number": 142,
  "pr_title": "Tighten checkout state handling",
  "author_email": "engineer@example.com",
  "pushed_at": "2026-05-09T01:20:00.000Z",
  "vercel_deployment_id": "dpl_123",
  "static_graph": {},
  "diff": {
    "routes_added": ["/checkout/review"],
    "routes_removed": [],
    "routes_modified": ["/checkout"],
    "edges_added": [],
    "edges_removed": [],
    "middleware_changed": false
  }
}

commit_sha and static_graph are required. previous_commit_sha may be null on the first deploy. Empty diffs are valid.

Verify

After the first successful upload:

1. Project setup shows Deploy received.
2. Activity shows the deploy record.
3. The deploy detail page opens from the returned dashboard URL.
4. New observations can attach to the deploy window.

Failure policy

Fail CI on parser hard errors, authentication rejection, or invalid payloads. Retry transient network failures. If your team soft-fails deploy attribution, make that choice explicit in the workflow logs.