This is the abridged developer documentation for Central Agentic Ops # Monitor and control GitHub Agentic Workflows at scale. > Keep track of all runs, costs, and outcomes of your GitHub Agentic Workflows across repositories. Set execution scope and rollout policy. # What Is Central Agentic Ops? > Observe, evaluate, and operate agentic work across repositories, with shared visibility and controlled rollout. You have workflows triaging issues in one repository and investigating failures in another. **Central Agentic Ops (CAO)** helps you understand and operate this work across repositories: observe activity, evaluate available cost and outcome evidence, and coordinate the execution and rollout of shared workflows. Existing workflows stay with their owners; shared work does not require moving every workflow into one central repository. **GitHub Agentic Workflows (AWs)** are AI-powered workflows that run in GitHub Actions. You describe a task in Markdown, and an agent carries it out with configured tools and permissions. They can respond to events, run on a schedule, or be requested on demand. CAO monitors these workflows, not every ordinary Actions job. [Learn about GitHub Agentic Workflows](https://github.github.com/gh-aw/). **[Set up CAO and monitor your workflows](/gh-cao/setup-quickstarts/)**. Connect one repository to get started. ## What you can do today [Section titled “What you can do today”](#what-you-can-do-today) | Capability | What it gives you | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Observe activity** | See collected activity across configured repositories, inspect recorded runs, and follow them back to GitHub. | | **Evaluate results** | Inspect costs, outputs, and outcomes where evidence is available. Use them to investigate what the work produced, not just whether it ran. | | **Scale and roll out shared work** | Standalone workflows and campaigns can opt into admission and bounded rollout across explicitly allowed repositories. In `review` mode, proposals go to a review destination; target repositories stay unchanged until live output is explicitly authorized. | Workflows can stay repository-local, be shared across projects, or run centrally. **Campaigns are one opinionated way to package, scale, and roll out shared work, not the only operating pattern.** Integrated review and rollout controls also support [standalone agentic workflows](/gh-cao/configuration/#standalone-agentic-workflows), but do not apply automatically to every observed workflow. For example, after an issue-triage workflow runs, you can inspect its run and follow the collected evidence to see what it produced. The dashboard helps you investigate whether the work was useful; a green run alone does not answer that. **A successful run is not automatically a successful outcome.** Missing cost or outcome evidence is not proof of zero cost or success. ## See the product [Section titled “See the product”](#see-the-product)  1 2 3 Public sample, 19 October 2026, after import completed. Not a live feed. [Open full-size capture](https://github.com/user-attachments/assets/1c408552-1a2d-45cc-967e-b46d8811798d). 1. **Start with your repositories.** See configured projects in one place. 2. **Read activity.** Ranked bars compare distinct retained runs. Zero means no retained runs, not confirmed inactivity. 3. **Follow outputs.** Inspect retained issue outputs; output counts alone do not prove successful outcomes. [Explore the public Repositories view](https://githubnext.github.io/gh-cao/cao/#page-repositories). Wait for import to finish before reading the charts. See the [dashboard guide](/gh-cao/dashboard/) for more. ## How evidence reaches the dashboard [Section titled “How evidence reaches the dashboard”](#how-evidence-reaches-the-dashboard) A **control repository** is an ordinary GitHub repository that stores your CAO configuration, holds credentials in Actions secrets, and runs collection and participating shared workflows. CAO Activity collects read-only evidence from the repositories you configure and publishes a snapshot for the dashboard: ``` flowchart TB accTitle: Monitoring existing agentic workflows accDescr: CAO Activity collects read-only evidence from configured repositories and publishes a snapshot for the shared dashboard. Observation grants no write authority. workflows["Existing AWs"] -->|"Read evidence only"| activity["CAO Activity"] activity -->|"Collected snapshot"| dashboard["Shared dashboard"] ``` The dashboard shows collected evidence, not a live feed. Collection can be partial or stale; an empty chart does not establish that no workflows ran. See [CAO Activity](/gh-cao/activity/) for collection and data-quality details. ## Essential safety boundaries [Section titled “Essential safety boundaries”](#essential-safety-boundaries) * **Seeing is not authorizing.** Observing a workflow grants no write authority. Collecting evidence does not change its permissions or authorize writes. * **Local owners keep control.** Project workflows and review requirements stay with their owners. A shared dashboard does not transfer credentials or authority. * **Public means public-safe.** Use a public control repository only when its configuration, run metadata, dashboard data, evidence, and review outputs can be public. A private repository does not by itself guarantee private Pages; [setup](/gh-cao/setup-quickstarts/) checks publication visibility. ## Get started [Section titled “Get started”](#get-started) **[Set up CAO and monitor your workflows](/gh-cao/setup-quickstarts/)**. Connect a repository to see its existing evidence. Explore [workflow operating patterns and ownership](/gh-cao/deployment-and-governance/) or [browse campaigns](/gh-cao/catalog/) for shared tasks and rollout. # Set Up CAO > Set up CAO, monitor one repository, and explore your dashboard before adding automation. This guide walks you through installing CAO in a control repository, connecting one repository to monitor, and publishing a dashboard of its existing GitHub Agentic Workflow runs, costs, and outcomes. This setup is for monitoring only. You can add an agentic workflow or a campaign later if you choose. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * You need **Git**, **Bash**, **`curl`**, **Node.js 24+**, and **GitHub CLI 2.68+**. * Run **`gh auth login`** if needed. * You need permission to configure **Actions**, **credentials**, and **Pages** in your control repository. * CAO lives in a **control repository** that stores its configuration and runs collection. Prefer a separate repository; the repository you monitor does not need CAO installed in it. * Use a **private control repository** for private or internal evidence. **Dashboard visibility** is a separate choice: a private repository does **not** guarantee a private Pages site. Setup checks this and asks before allowing public publication. ## 1. Install CAO [Section titled “1. Install CAO”](#1-install-cao) From a clean checkout of your chosen control repository, on its default branch: ```bash curl -fsSL https://raw.githubusercontent.com/githubnext/gh-cao/main/install.sh | bash ``` **Ready:** the CAO runtime, Activity collector, and dashboard workflows are installed locally. No campaign is installed or run. ## 2. Connect one repository [Section titled “2. Connect one repository”](#2-connect-one-repository) ```bash gh cao setup ``` Follow **Repositories → Connections → Review and apply**: 1. Enter the exact `OWNER/REPOSITORY` you want to monitor, not an organization wildcard. The control repository stays included in scope. 2. Connect authentication. Setup offers authentication choices based on that scope; check the selected profile’s prerequisites before approving. 3. Review the repository list, credentials, and dashboard visibility, then apply. **Ready:** repository scope and authentication are configured. Setup installs no campaign and runs no workflow; it does not commit or push. The campaign map in `.github/workflows/cao.json` should remain empty. Need help choosing credentials? See [Authentication](/gh-cao/authentication/). Run setup in an interactive terminal for this guided path; headless setup only supports the exact current public control repository, not an external target. ## 3. Publish your configuration [Section titled “3. Publish your configuration”](#3-publish-your-configuration) Check the installation and inspect the installed files: ```bash gh cao doctor git status --short git diff -- .github ``` Check that `.github/workflows/cao.json` names only the intended repositories and that `control-plane.campaigns` is `{}`. Do not publish private evidence to a public dashboard. Commit the CAO files and push to the control repository’s default branch: ```bash git add .github activity dashboard git commit -m "Set up CAO monitoring" git push ``` **Ready:** GitHub Actions can use your reviewed configuration. Check **CAO validation** in Actions for full policy and workflow validation. The installation includes scheduled Activity collection; pushing the policy also triggers collection. This collects evidence, not new agentic work. ## 4. Open your dashboard [Section titled “4. Open your dashboard”](#4-open-your-dashboard) In the control repository’s **Actions** tab, wait for **CAO Activity** and then **CAO Dashboard** to complete, including its Pages deployment. Open the site link in **Settings → Pages**. If collection has not started, request it once from the control checkout: ```bash gh workflow run cao-activity.yml ``` Activity refreshes the evidence; it does not run the workflows you monitor. Successful collection triggers dashboard publication automatically. Check the Actions runs for progress rather than repeatedly dispatching collection. **Your first look:** find the repository in **Overview**, open **Runs**, and follow a run back to its evidence. Costs and outcomes appear where available; missing evidence is not proof of zero cost or success. **No Agentic Workflow history yet?** An empty dashboard is expected. CAO monitors GitHub Agentic Workflows, not every ordinary Actions job. You can finish setup without generating a run. Preview the [sample dashboard](https://githubnext.github.io/gh-cao/cao/) to see populated views, or return after your existing workflows have run and Activity has refreshed. ## Optional: add automation later [Section titled “Optional: add automation later”](#optional-add-automation-later) Monitoring is enough to get started. When you have a task you want CAO to perform, browse the [campaign catalog](https://githubnext.github.io/gh-cao/catalog/). Install a chosen campaign with: ```bash gh cao campaigns add githubnext/gh-cao/CAMPAIGN ``` Installation is not execution. Review and commit its workflows and policy together before enabling or running it. Start in **review** mode with **one repository**; model access and AI credits are separate prerequisites. See [Roll out a campaign](/gh-cao/rollout-and-routing/) for the execution steps. Want a manual campaign example instead? The separate [Repo Assist walkthrough](/gh-cao/repo-assist-quickstart/) starts from a configured control repository and shows how to request one review-only maintenance proposal. It is optional, not a prerequisite for monitoring. # Portfolio Intelligence Computation > Correlate runtime-health evidence into deterministic, review-only Decisions with Campaign contracts and operator feedback. # Portfolio intelligence computation [Section titled “Portfolio intelligence computation”](#portfolio-intelligence-computation) The `intelligence` computation answers: > Which current operational conditions should an operator review now or soon, and which candidate signals should be suppressed? It consumes the versioned [runtime-health result](/gh-cao/computation-runtime-health/), compiled Campaign intelligence contracts, an optional previous result, and optional fingerprint-bound feedback. It emits advisory Decisions and suppressions. It does not admit Work, dispatch workers, or grant authority. The current measure contract is: ```json { "measureId": "portfolio-decisions", "measureVersion": "1.2.0" } ``` ## Run it [Section titled “Run it”](#run-it) ```bash gh cao download gh cao computation intelligence ``` Evaluate one Campaign: ```bash gh cao computation intelligence --campaign dependabot ``` Replay a prior result and apply operator feedback: ```bash gh cao computation intelligence \ --previous prior-intelligence.json \ --feedback decision-feedback.json ``` Use `--database FILE` and `--inventory FILE` together to evaluate another canonical snapshot. ## Candidate formation [Section titled “Candidate formation”](#candidate-formation) The computation applies these deterministic stages: 1. Convert each runtime-health error group into a stable signal. 2. Suppress signals for `observed-extra` targets. 3. Suppress signals while `recoveryMayBeInProgress` is true. 4. Correlate remaining signals by exact Campaign identity and runtime error key. 5. Produce one Decision for each correlation group. 6. Apply feedback only when both the Decision ID and input fingerprint match. 7. Order Decisions by state priority and stable Decision ID. Correlation does not use timestamps, physical ledger order, Git merge order, or runtime scheduling as a tie-breaker. ## Decision state [Section titled “Decision state”](#decision-state) The initial `protect` measure uses observed recurrence: * `act-now` when the correlation group contains at least three observed failures; * `decide-soon` when it contains fewer than three. The threshold is recorded in `sensitivity` and the `decisionTrace`. This is not a probability or a claim about expected benefit. Every current recommendation is: ```json { "operation": "investigate-runtime-failure", "mode": "review", "dispatchable": false } ``` The Decision includes alternatives to defer, do nothing, or obtain additional evidence. Its execution-authority hard gate is `not-evaluated` with `dispatch-prohibited`. ## Identity and replay [Section titled “Identity and replay”](#identity-and-replay) `decisionId` identifies the semantic condition: the Campaign, Decision class, operation, and correlated runtime error key. It remains stable when the underlying evidence changes. `inputFingerprint` identifies the exact measure version, threshold, Campaign contract, and signal fingerprints used for one evaluation. It changes when relevant evidence or configuration changes. Passing an unchanged result through `--previous` reuses the same logical Decisions. An incompatible measure version or malformed previous result is rejected rather than silently reused. ## Campaign contracts and quality [Section titled “Campaign contracts and quality”](#campaign-contracts-and-quality) Each Decision references the compiled Campaign intelligence contract used for that evaluation. The fingerprint therefore changes when declared Campaign semantics change. Campaign-authored semantics arrive through the normalized `intelligenceDeclaration` on the canonical Campaign record. The compiled contract exposes the declaration version and Campaign identity separately from the 17 semantic fields. See [Intelligence](/gh-cao/intelligence/#author-a-campaign-declaration) for the authoring and installation format. Decision quality combines: * runtime-health availability and provenance; * Campaign-contract completeness and maturity; * signal coverage; * target attribution coverage; and * contradiction state. A partial Campaign contract produces a partial Decision even when runtime failure evidence is available. This is intentional: CAO can report a recurring failure without pretending it knows the Campaign’s outcome, expected value, schedule rationale, or attention cost. ## Suppressions [Section titled “Suppressions”](#suppressions) The computation currently emits three suppression rules: | Rule | Meaning | | ------------------------------- | ------------------------------------------------------------------ | | `outside-declared-target-scope` | Evidence belongs to a Repository that is not explicitly enrolled. | | `recovery-in-progress` | A newer active Run may already be recovering the condition. | | `unchanged-terminal-result` | Terminal feedback already resolved the exact Decision fingerprint. | Suppressions retain the subject, signal fingerprint, reconsideration condition, and related Decision ID when applicable. They are historical explanations, not deleted evidence. ## Feedback [Section titled “Feedback”](#feedback) Feedback uses a versioned envelope: ```json { "contractVersion": "1.0.0", "records": [{ "decisionId": "runtime-health-decision:...", "inputFingerprint": "sha256:...", "disposition": "deferred", "observedAt": "2026-10-01T11:00:00Z", "actor": "operator:octocat", "authority": "control-repository-review" }] } ``` Allowed dispositions are: | Disposition | Effect for matching evidence | | ------------ | ----------------------------------------------------- | | `accepted` | Terminal; suppress the unchanged Decision. | | `rejected` | Terminal; suppress the unchanged Decision. | | `superseded` | Terminal; suppress the unchanged Decision. | | `recovered` | Terminal; suppress the unchanged Decision. | | `expired` | Terminal; suppress the unchanged Decision. | | `deferred` | Nonterminal; attach feedback and retain the Decision. | | `unresolved` | Nonterminal; attach feedback and retain the Decision. | Feedback for the same Decision ID but an older input fingerprint is reported as stale and cannot suppress changed evidence. Feedback for an absent Decision ID is reported as unmatched. The complete bounded feedback envelope remains in the result for inspection. `accepted` records a recommendation disposition only. It is not accepted outcome evidence or operational-value attainment. ## Result shape [Section titled “Result shape”](#result-shape) The result contains: ```json { "measureId": "portfolio-decisions", "measureVersion": "1.2.0", "inputFingerprint": "sha256:...", "evidenceQuality": {}, "evaluatedDecisionClasses": ["protect"], "agentInvocations": 0, "campaignContracts": [], "feedback": {}, "signalCount": 0, "correlatedCandidateCount": 0, "decisionCount": 0, "suppressionCount": 0, "reusedDecisionIds": [], "decisions": [], "suppressions": [], "asOf": null } ``` Each Decision includes: * recommendation, alternatives, and consequences; * hard gates and capacity requirements; * normalized quality and evidence references; * Campaign-contract identity and fingerprint; * applicable feedback; * correlation and sensitivity information; and * a trace of inputs, measure versions, rules, assumptions, thresholds, gates, constraints, and tie-breakers. Evidence references are bounded to 50 canonical Run IDs. ## Interpretation limits [Section titled “Interpretation limits”](#interpretation-limits) The current computation evaluates only the `protect` Decision class over runtime-health evidence. It does not yet: * forecast AI Credit or human-attention demand; * evaluate schedule fitness or Campaign overlap; * compare operational value across Campaigns; * select a portfolio under explicit capacity constraints; * evaluate execution authority; or * dispatch a selected worker. Those capabilities require additional declared Campaign facts and independently versioned measures. See the [intelligence overview](/gh-cao/intelligence/) for the planned sequence. # Runtime Health Computation > Evaluate current Campaign, orchestrator, and worker-target runtime health from canonical Run evidence. # Runtime health computation [Section titled “Runtime health computation”](#runtime-health-computation) The `runtime-health` computation answers: > Has each evaluated Campaign partition produced a successful Run, is it running, or does its current evidence require attention? It is a deterministic measure over canonical Campaign, Workflow, Repository, and Run records. It does not inspect raw workflow logs, call GitHub, diagnose repository outcomes, or authorize remediation. The current measure contract is: ```json { "measureId": "runtime-health", "measureVersion": "1.0.0" } ``` For the normative computation model, see the [Computations Specification](https://github.com/githubnext/gh-cao/blob/main/specs/computations.md). ## Run it [Section titled “Run it”](#run-it) ```bash gh cao download gh cao computation runtime-health ``` Evaluate one Campaign: ```bash gh cao computation runtime-health --campaign dependabot ``` Include bounded diagnostic evidence for one Campaign: ```bash gh cao computation runtime-health --campaign dependabot --diagnose ``` `--diagnose` requires `--campaign`. Use `--database FILE` and `--inventory FILE` to evaluate another canonical snapshot and its matching inventory. ## Evaluation partitions [Section titled “Evaluation partitions”](#evaluation-partitions) The query boundary selects and orders two partition kinds: | Partition | Identity | | ------------- | ------------------------------------------------ | | Orchestrator | Campaign and orchestrator Workflow | | Worker target | Campaign, worker Workflow, and target Repository | Runs must be supplied newest first by Run time, GitHub Run ID, and attempt. The measure rejects incorrectly ordered input rather than silently sorting it, because a wrong success boundary can change the answer. For each partition, evaluation stops at the latest observed successful Run. Only newer Runs contribute to the current failure streak. This prevents old, already-recovered failures from remaining active forever. ## Answers [Section titled “Answers”](#answers) | Answer | Meaning | | -------------- | --------------------------------------------------------------------- | | `yes` | The latest relevant terminal boundary is a success. | | `running` | There is active Run evidence and no newer terminal failure. | | `no` | One or more terminal non-successes occurred after the latest success. | | `not-observed` | No Run was observed for the selected partition. | | `unknown` | Available evidence cannot establish a reliable state. | `needsAttention` is true for `no`, `not-observed`, and `unknown`. It is false for `yes` and `running`. A terminal failure followed by an active Run sets `recoveryMayBeInProgress: true`. Portfolio intelligence uses this field to suppress a new recommendation until the active Run reaches a terminal state. ## Orchestrator gate [Section titled “Orchestrator gate”](#orchestrator-gate) Orchestrators are evaluated before workers: * An orchestrator answer of `no` blocks worker evaluation. * Missing or indeterminate orchestrator evidence makes worker evaluation indeterminate. * Workers are evaluated only when all selected orchestrator evidence is eligible. This avoids interpreting missing worker results as worker failures when the Campaign could not dispatch work successfully. Worker observations also retain target-scope membership: * `expected` means the Repository is in the declared target scope. * `observed-extra` means execution evidence exists outside that scope. * `unknown` means membership could not be established. Observed-extra partitions remain historical evidence but do not worsen the configured Campaign aggregate. Portfolio intelligence suppresses their failure signals instead of recommending action against an undeclared target. ## Failure groups [Section titled “Failure groups”](#failure-groups) Terminal non-successes after the success boundary are grouped by the first available classification: 1. `failureKind`; 2. `classification`; 3. `conclusion`; or 4. `unknown-error`. Each group reports: * occurrence and distinct Run-attempt counts; * conclusion counts; * latest observation time; * bounded failure-job and failure-step labels; and * bounded canonical Run references. Output is capped at 20 error groups and 20 Run references per group. Omitted counts remain explicit. ## Result shape [Section titled “Result shape”](#result-shape) The portfolio result contains: ```json { "measureId": "runtime-health", "measureVersion": "1.0.0", "campaignResults": [], "partitionResults": [], "errorGroups": [] } ``` `campaignResults` summarizes the orchestrator gate and aggregate answer. `partitionResults` explains every evaluated partition and its success boundary. `errorGroups` is the bounded input consumed by [portfolio intelligence](/gh-cao/computation-intelligence/). With `--diagnose`, the result also contains bounded canonical Run metadata, audits, tool errors, firewall blocks, safe-output observations, and a GitHub Actions Run link when available. Diagnostics explain where to investigate; they do not change the measure answer. ## Interpretation limits [Section titled “Interpretation limits”](#interpretation-limits) Runtime success means only that GitHub Actions recorded a successful Run. It does not prove that: * a repository outcome was attained; * an output was accepted; * the Campaign created operational value; or * another execution is authorized. Use Campaign-specific operational-value evidence for outcome attainment and the reviewed CAO policy for authority. # Intelligence > Understand how CAO turns canonical operational evidence into deterministic, review-only Decisions. # CAO intelligence [Section titled “CAO intelligence”](#cao-intelligence) The CAO intelligence layer turns canonical Activity and Campaign inventory evidence into compact, deterministic findings for operators. It answers: * What is failing or missing now? * Which observations describe the same underlying condition? * Which conditions require attention now or soon? * Which signals should be suppressed because they are outside scope or recovery is already underway? * What evidence and assumptions support each recommendation? Intelligence is a derived, review-only layer. It does not admit Work, acquire a claim, dispatch a worker, change rollout mode, grant credentials, or mutate a repository. A high-priority Decision is evidence for human review, not permission to execute. For the normative contract, see the [Intelligence Specification](https://github.com/githubnext/gh-cao/blob/main/specs/intelligence.md). ## Data flow [Section titled “Data flow”](#data-flow) ``` flowchart LR A[Canonical Activity evidence] --> R[Runtime health] I[Canonical Campaign inventory] --> C[Campaign intelligence contracts] R --> P[Portfolio intelligence] C --> P F[Operator feedback] --> P P --> D[Advisory Decisions] P --> S[Suppressions] ``` The layer currently exposes two CLI computations: 1. [Runtime health](/gh-cao/computation-runtime-health/) evaluates orchestrators and worker-target partitions against the latest observed success boundary. 2. [Portfolio intelligence](/gh-cao/computation-intelligence/) correlates current failure signals into stable, review-only Decisions and applies fingerprint-bound operator feedback. Both computations consume the downloaded canonical snapshot. They do not query GitHub during evaluation. ## Run the current layer [Section titled “Run the current layer”](#run-the-current-layer) Download or refresh the deployed snapshot: ```bash gh cao download ``` Evaluate the complete portfolio: ```bash gh cao computation runtime-health gh cao computation intelligence ``` Narrow either computation to one Campaign: ```bash gh cao computation runtime-health --campaign dependabot gh cao computation intelligence --campaign dependabot ``` Each command writes JSON to standard output. Diagnostics and runtime warnings stay on standard error, so the result can be redirected safely: ```bash gh cao computation intelligence > intelligence.json ``` See [CAO Commands](/gh-cao/cao-cli/) for common CLI options. ## Campaign intelligence contracts [Section titled “Campaign intelligence contracts”](#campaign-intelligence-contracts) Every evaluated Campaign receives a stable, versioned intelligence contract. The contract has 17 semantic fields covering: * the repository-native problem and eligible opportunity; * intended outcome and accepted outcome evidence; * target population and intervention class; * trigger, schedule, rationale, and maximum detection delay; * resource and human-attention envelopes; * overlap identity and output/approval policy; * maturation, deduplication, backoff, and stop conditions; and * operational-value definition. The compiler copies only declared or canonical facts. It does not reinterpret a Campaign description, README, workflow execution, or generated issue as an outcome contract. Undeclared fields remain `null`; numeric evidence distinguishes `zero`, `missing`, `available`, and `malformed`. Current inventory commonly provides only a resource envelope and, for explicitly targeted Campaigns, a target population. Such contracts correctly report `partial` completeness. A partial contract can support operational warnings, but it cannot justify claims about expected value, outcome attainment, schedule fitness, or Campaign overlap. ## Author a Campaign declaration [Section titled “Author a Campaign declaration”](#author-a-campaign-declaration) Place `intelligence.json` next to the Campaign’s `aw.yml`: ```json { "contractVersion": "1.0.0", "campaign": "dependabot", "fields": { "intendedOutcome": { "statement": "Reduce open dependency security risk." }, "stopConditions": { "conditions": ["No actionable dependency-maintenance work remains."] } } } ``` After gh-aw installs or updates the Campaign, run the standard CAO materializer. It copies the declaration from the reviewed Campaign revision to: ```text .github/cao/intelligence/dependabot.json ``` The envelope is strict: * `campaign` must match the lowercase Campaign slug; * `contractVersion` must be supported; * `fields` may contain only the 17 defined semantic fields; * unknown values must be omitted, not declared as `null`; and * the catalog and installed copies must be canonically identical. Malformed, mismatched, or conflicting declarations fail inventory construction closed. The declaration is descriptive evidence only; placing `mode`, targets, credentials, or output authority in it cannot widen reviewed CAO policy. The Dependabot Campaign is the initial evidence-grounded pilot. Its declaration references the existing operational-value definition and preserves `backoff` as unknown because no explicit backoff contract has been authored. ## Evidence quality [Section titled “Evidence quality”](#evidence-quality) Every Campaign contract, Decision, and portfolio result preserves normalized quality dimensions: | Dimension | What it describes | | -------------------- | --------------------------------------------------------- | | Availability | Whether required evidence exists and can be used. | | Completeness | Whether all required fields or observations are present. | | Freshness | The declared state and observation time. | | Coverage | Measured numerator and eligible denominator, when known. | | Maturity | Whether enough time has elapsed to evaluate the evidence. | | Provenance | Which canonical sources produced the result. | | Attribution coverage | How much evidence can be assigned to its subject. | | Contradiction state | Whether evidence conflicts. | Invalid quality values fail closed as `malformed`. Missing denominators remain `null`; they are not replaced with observed counts. `fresh` and `stale` require a valid observation time and an applicable freshness rule. ## Decisions and feedback [Section titled “Decisions and feedback”](#decisions-and-feedback) A Decision has a stable identity for its semantic condition and a separate input fingerprint for the exact evidence that produced it. This distinction allows CAO to: * reuse unchanged Decisions during deterministic replay; * recognize changed evidence without inventing a new semantic identity; * apply feedback only to the exact evidence an operator reviewed; and * retain feedback against older evidence as stale, inspectable history. Terminal feedback (`accepted`, `rejected`, `superseded`, `recovered`, or `expired`) suppresses only an unchanged Decision. Nonterminal feedback (`deferred` or `unresolved`) remains attached without suppressing it. Feedback is descriptive evidence. `accepted` means the recommendation was accepted for the reviewed fingerprint; it does not mean the intended repository outcome was attained, and it grants no execution authority. ## What the current layer can and cannot conclude [Section titled “What the current layer can and cannot conclude”](#what-the-current-layer-can-and-cannot-conclude) The current implementation can reliably conclude that a bounded operational condition is recurring, group related failure evidence, identify recovery and scope suppressions, and preserve human review. It cannot yet determine which intervention creates the most operational value. That requires explicit Campaign outcomes, schedules, budgets, attention limits, overlap identities, and stop conditions, followed by deterministic resource, schedule, overlap, and portfolio-selection measures. The planned delivery sequence is: 1. ingest the missing Campaign intelligence facts; 2. add resource, schedule, overlap, attention, and Campaign-design measures; 3. apply hard gates and explicit capacity constraints; 4. present Decision Briefs through Dashboard Language; 5. add authoring validation and historical simulation; and 6. integrate a later coordination layer for bounded dispatch. The intelligence contracts and fingerprints are intentionally independent of that future coordination storage. # Release promotion controls > Gate the immutable prerelease-to-latest transition with independent approval and exact-source evidence. **The approval boundary is prerelease to latest, not PR merge or prerelease creation.** The automated Release workflow still prepares assets, publishes an immutable prerelease, and adds highlights without an environment approval. Existing PR path filters and branch rulesets are unchanged. These controls support release evidence and change authorization (SOC 2 CC7.1 and CC8.1). They are control design, not certification or proof of operation over an audit period. They do not enable hosted CLI execution, widen CAO policy, or change authority over enrolled targets. ## Promotion flow [Section titled “Promotion flow”](#promotion-flow) After the complete Release workflow succeeds, dispatch **Promote prerelease to latest** (`release-promote.yml`) from the current default branch with its existing `vX.Y.Z` tag: ```sh gh workflow run release-promote.yml --ref main -f tag=vX.Y.Z ``` The workflow does not create a release, rebuild its assets, or move its tag. It requires an existing immutable, published prerelease whose tag and `target_commitish` identify the same full commit SHA reachable from the default branch. The runtime archive and its checksum, six `gh-cao-OS-ARCH` binaries (`.exe` on Windows), and `checksums.txt` must all have immutable SHA-256 digests, and the exact-SHA prerelease preparation/highlights workflow must have succeeded. The candidate must advance the current stable semantic version; rollback, repromotion, and first-stable bootstrapping are not supported by this workflow. Before requesting approval, it verifies the live `release-latest` environment, binds the candidate, notes digest, asset digests, previous latest release, and exact-SHA CodeQL analysis identities, then runs fresh validation: | Promotion job | Required evidence | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `Validate release contracts` | `npm run check`: root lint, typechecks, unit/integration/load contracts, SVG checks, TypeSpec artifacts, seeded workflow compilation, and docs | | `Validate release dashboard` | Dashboard typecheck, lint, unit tests, production build | | `Validate release server` | Go formatting, lint, and server tests | These are jobs in the promotion run, not required PR status checks. Every job runs against the exact candidate SHA, without path filters or skip-as-success fallbacks. Skipped, cancelled, failed, or missing validation prevents promotion. Candidate validation has only read permissions; the privileged job checks out the trusted workflow SHA, never the candidate source. CodeQL evidence must cover Actions, Go, JavaScript/TypeScript, and Python on the exact candidate SHA from default-branch analysis. The verifier searches the most recent 1,000 default-branch analyses and retrieves each selected analysis’s SARIF, checking result completeness and linked alert identities. High/critical security findings or error-level results block promotion even if an alert was dismissed; no automatic waiver or scanner suppression is provided. Missing, inaccessible, failed, or mismatched evidence blocks. Low/medium non-error findings remain available for reviewer assessment. An analysis on a PR head or another commit is not release evidence. The workflow records candidate/evidence JSON in a 90-day Actions artifact and the job summary before the protected job becomes eligible. An independent human reviewer examines the release notes, SHA, validation jobs, and scanner evidence, then approves the `release-latest` environment. GitHub approval history must identify a human other than both the original and rerun actor. After approval, the workflow rereads the environment, candidate, latest, preparation result, and scanner evidence. Changed evidence or a newer default branch head requires a new dispatch and approval. Reruns are rejected to avoid reusing approval history from an earlier attempt. Promotion runs share one non-cancelling concurrency group. Only then does the privileged job update the existing release with `prerelease: false` and `make_latest: true`, verifying the stable/latest result. Failure before the update leaves the candidate a prerelease. A failed readback after the update is reported as failure, not silently rolled back or declared successful; an operator must inspect the actual release state. Promotion’s GitHub.com `cache-mode: read` denies cache writes through scoped job tokens. No job overrides it. Unsupported GHES versions must omit this key without an equivalent guarantee. Docs cache npm downloads, never `node_modules`, and always run `npm ci` with lockfile integrity checks. Approval follows validation and does not protect earlier execution. Dashboard delivery is unchanged. ## Administrator setup (not performed by this change) [Section titled “Administrator setup (not performed by this change)”](#administrator-setup-not-performed-by-this-change) 1. Independently review and land the promotion workflow. Keep the existing prerelease automation, branch rulesets, deletion protections, and force-push prohibitions unchanged. 2. Create the GitHub environment **`release-latest`** in repository Settings > Environments. Configure at least one suitable required reviewer or reviewer team, enable **Prevent self-review**, and disable **Allow administrators to bypass configured protection rules**. 3. Select deployment branches/tags and allow exactly the default **branch** (`main` here), with no wildcard or tag policy. Keep existing CodeQL default setup configured for the four required language categories. 4. Run the read-only check below before any promotion. A missing environment or insufficient protection must be fixed by an administrator, not created implicitly by starting a job that references its name. ```sh node scripts/verify-release-environment.mjs githubnext/gh-cao ``` The supported `.github/github-app.yml` exposes this as a manual verification script. It only performs GET requests. No credentials, environment mutations, branch-policy mutations, or release writes occur in the verifier. 5. Dispatch a candidate promotion, inspect the bound evidence and validation, and obtain independent environment approval. Retain environment configuration, approval history, exact SHAs, workflow/job links, scanner analysis IDs, and the promotion receipt in the approved evidence system beyond Actions retention when required. **Administrative boundary:** GitHub environment protection gates this workflow job, not every possible release edit. A user or App with repository `contents: write` can still edit releases directly through GitHub’s UI/API. Administrators must restrict that authority and require this promotion path operationally; this repository change cannot impose a release-specific UI/API permission boundary. The workflow uses `GITHUB_TOKEN`, whose release updates do not automatically trigger other Actions workflows. It promotes the release to latest only; downstream publication must use its separately authorized path. Repository releases have no conditional update primitive here, so concurrent out-of-band administrator edits remain an operational risk despite immediate revalidation and postcondition checks. ## Hosted CLI scanner disposition [Section titled “Hosted CLI scanner disposition”](#hosted-cli-scanner-disposition) Parent PR [#18462](https://github.com/githubnext/gh-cao/pull/18462), revision `81b7333a7cbb4cc5064ccb3f2c7d9dd22196d132`, [CodeQL check 117485353748](https://github.com/githubnext/gh-cao/runs/117485353748) reported a high-severity potential allocation overflow at `server/internal/hostedcli/apple_container.go`: `42 + len(spec.Args)`. This is scanner evidence, not independently established exploitation. The fix removes arithmetic from allocation sizing by appending variable arguments to a fixed slice literal. Tests preserve empty/single/many argument ordering and boundaries, without a CodeQL suppression. Dashboard test fixes preserve the intentional native `gh aw update` commands, explicit control-repository context, PR publication, and opt-in auto-merge. Neither local tests nor the prior merge-gate implementation prove promotion readiness: release promotion requires its own exact-SHA validation and scanner evidence plus independent approval. # Try a Repo Assist review > Manually install, review, and run one bounded Repo Assist campaign. # Try a Repo Assist review [Section titled “Try a Repo Assist review”](#try-a-repo-assist-review) To monitor existing Agentic Workflows without adding a campaign, start with [Set Up CAO](/gh-cao/setup-quickstarts/). This optional walkthrough uses ordinary campaign commands after setup; nothing commits, pushes, or dispatches on your behalf. ## 1. Install the campaign [Section titled “1. Install the campaign”](#1-install-the-campaign) From your configured control repository, install Repo Assist from a reviewed catalog revision: ```bash gh cao campaigns add githubnext/gh-cao/repo-assist gh cao campaigns mode preview repo-assist ``` Installation is not execution. Review `.github/workflows/cao.json` before publishing. Keep exact owner and repository allowlists for the control repository and the one existing target you explicitly select. Configure `control-plane.campaigns.repo-assist.targets` for that target, keep campaign mode and the maintenance worker ceiling at `review`, set `max-repositories` to `1`, enable only maintenance, and disable issue triage, issue fix, and PR upkeep. See the [campaign policy example](https://github.com/githubnext/gh-cao/blob/main/repo-assist/README.md#install) and [rollout guide](/gh-cao/rollout-and-routing/). Use a private control repository for non-public targets or evidence. A public control repository exposes workflow evidence, review outputs, and dashboard data. Repository-local workflow-token Activity access covers only the control repository: declare `control-plane.activity.repositories` accordingly, or configure appropriate cross-repository credentials. Target access and model authentication remain separate prerequisites; see [authentication](/gh-cao/authentication/). Inspect the diff and run `gh cao doctor`. Commit the reviewed workflows and policy together, then publish and immediately pause the orchestrator: ```bash git push gh workflow disable repo-assist.lock.yml ``` Keep it paused until Step 2 so its six-hour schedule does not request recurring work while you inspect the installation. Check **CAO validation** in Actions before execution. ## 2. Request one maintenance review [Section titled “2. Request one maintenance review”](#2-request-one-maintenance-review) The normal budgets are 250 AI credits for orchestration, 600 for maintenance, and a configurable output check (400 by default): up to **1,250 AI credits** under default limits, not expected consumption or measured usage. Replace the coordinates below and `main` with your control repository’s actual default branch. Enabling the orchestrator also enables its six-hour schedule. ```bash gh workflow enable repo-assist.lock.yml gh aw run repo-assist --ref main \ --raw-field target_repo="TARGET_OWNER/TARGET_REPOSITORY" \ --raw-field safe_output_repo="CONTROL_OWNER/CONTROL_REPOSITORY" \ --raw-field max_repos="1" \ --raw-field safe_output_mode="review" gh workflow disable repo-assist.lock.yml ``` Pause the orchestrator even if dispatch fails if you do not want scheduled work. Disabling does not cancel an already requested run. Inspect Actions to follow the orchestrator and maintenance worker; repeating `gh aw run` requests new work, not a status check. Maintenance proposes one small validated patch in a control-repository review issue and downloadable review bundle, or records a no-op. It never applies changes to the target repository. A no-op is a valid result, and unavailable required evidence remains incomplete. Proposals are optional, not readiness grades or requirements for using CAO. ## 3. Collect and inspect evidence [Section titled “3. Collect and inspect evidence”](#3-collect-and-inspect-evidence) After inspecting the outcome, request collection: ```bash gh workflow run cao-activity.yml ``` This dispatch returns without waiting. Normal Activity push and schedule triggers may also collect evidence independently. Inspect the Activity run, then the dashboard workflow and its successful Pages deployment job; workflow success with a skipped deployment is not publication. Follow [Set Up CAO](/gh-cao/setup-quickstarts/#4-open-your-dashboard) to open the dashboard. Runtime success alone does not prove a proposal was applied or accepted. ## See more without running more [Section titled “See more without running more”](#see-more-without-running-more) Read [verified historical Repo Assist examples](https://github.com/githubnext/gh-cao/blob/main/repo-assist/README.md#see-repo-assist-in-action) without dispatching work or spending AI credits. No demo repository is created, and useful findings are not guaranteed. Other workers, recurring operation, additional targets, and live authority require separate reviewed choices. # What Dependabot / Update Planner measures > Definitions, evidence rules, and interpretation for the Dependabot / Update Planner operational-value report. This page explains the operational-value timeline in plain language. It defines what was measured; it does not decide whether the workflow caused the observed changes. ## How to read the timeline [Section titled “How to read the timeline”](#how-to-read-the-timeline) * The purple dotted line marks workflow adoption on `2026-09-17`. * The left side is pre-adoption evidence; the right side is post-adoption evidence. * Each dot is one immutable observation. Missing evidence is omitted, never treated as zero. * Workflow runs show execution activity only. They do not prove repository value. ## What was measured [Section titled “What was measured”](#what-was-measured) ### Open security alerts [Section titled “Open security alerts”](#open-security-alerts) * **What it tells you:** Open security alerts. This is a `primary` measure. * **Native measurement formula:** `Dependabot security alerts open at the cutoff` * **Unit:** `alerts` * **Goal:** Lower values are better. * **Chart display:** The chart shows the native value directly on a metric-specific axis. ### Open critical/high alerts [Section titled “Open critical/high alerts”](#open-criticalhigh-alerts) * **What it tells you:** Open critical/high security alerts. This is a `diagnostic` measure. * **Native measurement formula:** `Dependabot security alerts with critical or high severity open at the cutoff` * **Unit:** `alerts` * **Goal:** Lower values are better. * **Chart display:** The chart shows the native value directly on a metric-specific axis. ### Open Dependabot pull requests [Section titled “Open Dependabot pull requests”](#open-dependabot-pull-requests) * **What it tells you:** Open Dependabot pull requests. This is a `diagnostic` measure. * **Native measurement formula:** `Dependabot-authored dependency pull requests open at the cutoff` * **Unit:** `pull-requests` * **Goal:** Lower values are better. * **Chart display:** The chart shows the native value directly on a metric-specific axis. ## Evidence rules [Section titled “Evidence rules”](#evidence-rules) * **Repository:** `githubnext/gh-cao` * **Evidence population:** A Dependabot security alert in an authorized target repository that was open at the immutable observation cutoff. * **Collection:** Fetch Dependabot alert lifecycle records and Dependabot-authored pull-request lifecycle records once per supported repository, then reconstruct every requested cutoff locally from their authoritative timestamps. * **Observation window:** 7 days, sampled every 7 days * **Maturation delay:** 0 days * **Filters:** `Count alerts created no later than the cutoff and not fixed, dismissed, or auto-dismissed by that cutoff.`; `Count critical and high alerts separately without severity weighting.`; `Count Dependabot-authored pull requests created no later than the cutoff and not closed by that cutoff as a separate queue diagnostic.`; `Fail the observation closed when complete alert or pull-request lifecycle evidence is unavailable.` The same definitions and formulas are applied before and after adoption. The structured evidence, exact snapshots, provenance, units, and native values are recorded in the adjacent `dependabot-update-planner-timeline.json` artifact. ## Important limitation [Section titled “Important limitation”](#important-limitation) A before/after pattern is an association, not proof of causation. Other repository changes may explain some or all of the movement. Value-function SHA-256: `78540498a35c483cea4a7727ca961c3b2e0e94ca2c9604ff4b648064ad87ea34`