gh-cao

README

Central Agentic Ops

[!NOTE] Research prototype: Features and interfaces may change as the project evolves.

[!TIP] Agent setup router: When asked to create, bootstrap, initialize, or set up a Central Agentic Ops control plane, load and follow the setup skill. Use a separate control repository by default; any repository may explicitly run workflows it maintains in-tree as a source-managed control plane, including a catalog dogfooding its own workflows.

[!TIP] Agent debugging router: When a CAO deployment, credential, Agentic Workflow, Activity collection, or dashboard build fails, load and follow the debug-cao skill. Preserve the failing workflow commit and exact component versions before changing or rerunning the deployment.

Monitor GitHub Agentic Workflow runs, costs, and outcomes from one control repository. Add policy-governed operations when you are ready; CAO does not replace repository permissions, branch protections, or human review.

Get started: monitor one repository

Install the gh cao extension with GitHub CLI, then open guided setup from the root of an existing control-repository checkout:

gh extension install githubnext/gh-cao
gh cao setup

Git and authenticated GitHub CLI 2.68+ are required. Native setup prepares missing gh-aw, runtime files, and baseline policy without installing Node.js or adding or running a campaign.

[!TIP] SAML-token installation failure: If GitHub CLI cannot download the extension because your token lacks cross-organization SAML authorization, use the curl installer: curl -fsSL https://raw.githubusercontent.com/githubnext/gh-cao/main/install-gh-cao.sh | bash -s -- --setup. This fallback requires Bash, curl, and Node.js 24+; public tool downloads are anonymous, while stored credentials remain available for control-repository and runtime-provenance operations.

No checkout yet? Explicitly use gh repo create OWNER/CONTROL --private --clone or gh repo clone OWNER/CONTROL, then cd CONTROL before installation. Choose --public instead only for public evidence.

Follow Set Up CAO for scope, authentication, publication, and the first dashboard visit. Setup offers a separate default-No commit-and-push prompt; declining or unattended setup leaves files local. Publication returns deployment pending, not a ready dashboard. No campaign is installed or run. An empty dashboard is expected when there is no Agentic Workflow history.

Use a private control repository for non-public evidence. A private repository does not guarantee a private Pages site: verify dashboard visibility before publishing.

Optional, later: describe your outcome and scope in From Outcome to Execution, then try the Daily Repo Status quickstart or the Repo Assist review walkthrough. Campaigns are one first-class way to scale recurring work, not a prerequisite. Start with one repository in review; live outputs need explicit reviewed policy and declared safe-output capabilities. You can also read real Repo Assist reports without starting a workflow or spending AI credits.

Documentation

Read the documentation site, or start with the guide for your task:

Task	Guide
Understand CAO and its boundaries	What is CAO? and Architecture
Install and monitor existing workflows	Set Up CAO
Use or upgrade the CLI	CAO Commands
Choose and provision credentials	Authentication and credential setup
Host the dashboard	Deployment options and GitHub Pages
Interpret evidence	Dashboard
Analyze evidence with CLI or MCP	Agent analysis
Install skills or use a Copilot canvas	Agent plugin and canvas
Preview locally	Local serving modes
Add shared work	From Outcome to Execution and campaign catalog
Operate, update, or recover	Monitor and recover

For agents: llms.txt for navigation, llms-small.txt for compact context, and llms-full.txt for the full corpus.

Contributing and support

Read Contributing and the Code of Conduct. Use open issues and Support for help; report vulnerabilities privately through Security. Maintained by GitHub Next, with ownership in CODEOWNERS.

License

This project is licensed under the MIT License. See LICENSE for the full terms.