Repository activation runs

Repository activation is the path from a connected repository to the first durable EvalGate report. Start one activation for the selected repository identity, retain its run ID, and resume it after refreshes or reconnects.

Link once; pin every activation

The durable link is the organization, GitHub repository ID and owner/name, and selected repository-relative root. Branch and commit movement do not unlink the project. Every cloud activation is a separate immutable snapshot. requestedRef is a symbolic remote branch such as main; targetSha is the exact commit to evaluate; and remoteHeadSha is the branch head GitHub reported when EvalGate compared them. EvalGate builds intake from targetSha, never by silently substituting remoteHeadSha. Harness preset and manifest hash also belong to the snapshot identity. The observed relation (exact, behind, ahead, diverged, or unknown) and commit counts are time-sensitive observations. They are not part of the immutable manifest hash and are recomputed when status is requested.

Start once, then poll

The authenticated onboarding activation endpoint returns an activationRun object. Keep activationRun.id in durable client state; do not start another run on every page load or retry. The expected response includes:

{
  "activationRun": {
    "id": "activation-run-id",
    "lifecycle": "queued",
    "progress": { "stage": "queued", "completed": 0, "total": null, "findings": null },
    "identity": {
      "repositoryId": 123,
      "requestedRef": "main",
      "targetSha": "0123456789abcdef0123456789abcdef01234567",
      "rootPath": "",
      "harnessPresetKey": "node-pnpm",
      "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    },
    "observation": {
      "remoteHeadSha": "fedcba9876543210fedcba9876543210fedcba98",
      "relation": "behind",
      "aheadBy": 0,
      "behindBy": 2,
      "targetExists": true,
      "targetReachableFromRef": true,
      "observedAt": "2026-09-03T00:00:00.000Z"
    },
    "failure": null,
    "result": null,
    "report": null
  }
}

Poll the run using the returned ID:

GET /api/onboarding/activation/runs/{activationRunId}
Authorization: Bearer <EVALGATE_API_KEY>

Use bounded polling with the server’s retry guidance when provided. A refresh, navigation, or transient network failure should resume this GET; it must not initiate a second activation for the same identity.

Run states

State	Meaning	Client action
`approved`	The operator approved the selected identity and requested work.	Move to queued/running; do not restart.
`queued`	The activation is accepted and waiting for execution.	Poll.
`running`	Repository inspection or baseline work is executing.	Poll and show progress.
`partial`	Some evidence exists, but continuation is required.	Follow the returned continuation/report action.
`completed`	A durable report exists, including a non-empty result or an evidence-backed no-op result.	Open the report and continue to regression actions.
`failed`	The run stopped with an actionable error.	Follow `error.code`/`error.nextAction`; retry only when retryable.
`stale`	The exact snapshot or its lineage is no longer reusable. The durable repository link may still be valid.	Refresh evidence for the intended exact commit; relink only for an organization, repository, or root mismatch.

Terminal states are partial, completed, failed, and stale. A partial run has durable evidence but needs the returned next action before a baseline is ready. Never present queued or running as a completed report.

Retry semantics and one-time keys

Retry an interrupted start request with the same idempotency key and exact snapshot identity; a duplicate response returns the existing run. Stable activation identity includes repository ID, requested branch, target SHA, root, harness preset, and immutable manifest hash. A remote branch advancing after preview does not invalidate the request when the target still exists, remains reachable from the requested branch, and produces the same target intake. After a run explicitly reaches failed or stale, review the failure and submit a new start request with a new idempotency key. Retry GET polling on network errors, 408, 425, 429, and 5xx, respecting Retry-After. Repository linking does not implicitly mint an install/API key. Human CLI sessions are established by evalgate login; automation uses an explicitly provided secret such as EVALGATE_API_KEY. Never print credentials, persist them in browser history, or include them in reports. If a separately requested credential operation creates a key, it must revoke the key on failure or return a recoverable partial run with an explicit continuation action.

Checkout and evidence status

evalgate status --json keeps four questions separate:

link.status: Do durable organization, repository, owner/name, and root identities agree?
readiness.localGate: Can the configured local gate run?
readiness.cloudCanTargetCheckout: Can GitHub prove the exact checkout is an admissible cloud target?
readiness.cloudEvidenceMatchesCheckout: Does current cloud intake match the exact local repository/ref/target/root/manifest identity?

For example, a developer two commits behind main can remain fully linked and locally ready:

{
  "link": { "status": "linked" },
  "checkout": {
    "currentRef": "main",
    "localSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "remoteHeadSha": "dddddddddddddddddddddddddddddddddddddddd",
    "relation": "behind",
    "aheadBy": 0,
    "behindBy": 2,
    "dirty": false
  },
  "readiness": {
    "localGate": true,
    "cloudCanTargetCheckout": true,
    "pushRequired": false
  }
}

An unpushed target keeps the link and local gate but reports pushRequired and cannot start cloud-backed evidence. A diverged target requires an explicit appropriate branch. A force-pushed lineage makes prior cloud evidence stale or unverified without removing the durable link. A dirty worktree may run a local gate, but Git SHA alone cannot claim exact cloud reproduction of its uncommitted state.

Continue after the report

When the run reaches completed, follow its report reference and display the bound commit SHA and case/evidence count. From the report, agents may continue to a reviewed regression candidate, a fix proposal, or a CI proposal. These actions create reviewable artifacts. They do not apply code changes, open a pull request, or modify CI unless a separate governed application flow is explicitly available.

Minimum handoff

Return the activation run ID, exact repository identity, current state, report ID/URL when available, evidence or case count, next action, and any untested boundary. If the run fails, return the machine-readable error code and whether retrying is safe.

Get Started

Core Concepts

Guides

SDK Reference

Platform

Repository activation runs

Repository activation runs

Link once; pin every activation

Start once, then poll

Run states

Retry semantics and one-time keys

Checkout and evidence status

Continue after the report

Minimum handoff

​Repository activation runs

​Link once; pin every activation

​Start once, then poll

​Run states

​Retry semantics and one-time keys

​Checkout and evidence status

​Continue after the report

​Minimum handoff

Repository activation runs

Link once; pin every activation

Start once, then poll

Run states

Retry semantics and one-time keys

Checkout and evidence status

Continue after the report

Minimum handoff