> ## Documentation Index > Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Repository activation runs > Start, resume, and complete a durable repository activation run # 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: ```json theme={null} { "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: ```http theme={null} GET /api/onboarding/activation/runs/{activationRunId} Authorization: Bearer ``` 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: ```json theme={null} { "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.