Quickstart

Central Agentic Ops lets you run governed agentic operations across many repositories from one private GitHub repository, which we call the central control plane. Operation packages, credentials, rollout policy, and workflow runs stay in the control plane; target repositories do not receive copies of the workflows.

By the end of this guide, you will have created a control plane, installed the Dependabot operation, and completed one review run against a public target repository. You will verify that the operation selected the expected target, saved any proposal in the private control repository, and did not change the target.

Run a Reviewed Dependabot Operation

Estimated time: 15 minutes

This quickstart uses one public repository owned by the same organization as the control repository. That path requires no GitHub App or personal access token.

Prerequisites

Before you begin, make sure you have:

• a GitHub organization where you can create a private repository;
• one low-risk public repository in that organization to use as the target;
• GitHub Actions enabled for both repositories;
• GitHub CLI installed and authenticated;
• access to GitHub Copilot through organization billing for Agentic Workflow runs.

Check your GitHub CLI authentication:

gh auth status

If needed, sign in with repository and workflow access:

gh auth login --scopes repo,workflow

Using a private or cross-organization target?

Complete Configure Authentication before running the operation. The credential must cover the target repository, and its owner must be allowlisted.

Step 1 - Create the control repository

Choose names for the private control repository and public target repository. Replace the examples below with repositories you own:

CONTROL_REPO="acme/central-agentic-ops"
TARGET_REPO="acme/example-service"

gh repo create "$CONTROL_REPO" --private --clone
cd "${CONTROL_REPO##*/}"

The new private repository is the central control plane. Agentic Workflow definitions and credentials stay here; they are not installed in the target repository.

Keep the control plane private

The control repository holds credentials, rollout policy, and cross-repository operating records. Do not make it public.

Step 2 - Install the gh-aw extension

Install GitHub Agentic Workflows:

gh extension install github/gh-aw

If the extension is already installed, verify that it is available:

gh aw --help

Step 3 - Add the Dependabot operation

From the control repository, install the Dependabot operation package and CAO runtime from the same pinned catalog release. Replace <catalog-release> with a release tag or full commit SHA:

CAO_REF="<catalog-release>"
gh aw add "githubnext/gh-aw-cao/dependabot@${CAO_REF}"
mkdir -p .github/cao
for cao_file in control.mjs policy.mjs; do
  gh api --method GET "repos/githubnext/gh-aw-cao/contents/.github/cao/${cao_file}" \
    -f ref="$CAO_REF" --jq '.content' | base64 -d > ".github/cao/${cao_file}"
done

The package installs:

1. the Dependabot orchestrator, which selects repositories;
2. the Dependabot / Release Trains worker, which analyzes one selected repository;
3. shared authentication, routing, and fail-closed controls;
4. generated .lock.yml workflows that GitHub Actions executes.

The three .github/cao files are control-repository-owned policy runtime, not gh-aw package resources. Commit them with the workflows and policy so every run resolves one atomic revision. See Admission Gates for the checks this runtime performs before activation.

The installed operation is runnable after its package and worker workflow identities are declared in the control policy. Declared workers are enabled unless their policy sets enabled: false; undeclared or disabled identities are skipped by admission before agent execution.

Caution

Do not edit generated .lock.yml files directly. Update their Markdown sources and regenerate them with gh aw compile.

Step 4 - Set the first-run boundary

Create .github/workflows/cao.json with the target owner and package. The omitted package settings default to review, one repository, and 100 percent rollout:

.github/workflows/cao.json

{
  "version": 1,
  "control-plane": {
    "scope": {
      "allowed-owners": ["acme"]
    },
    "packages": {
      "dependabot": {
        "workers": {
          "release-train-updater": {
            "workflow": "dependabot-release-train-updater"
          }
        }
      }
    }
  }
}

Replace acme if your target has a different owner. Commit the workflow sources, generated locks, resolver resource, and policy together so github.workflow_sha identifies one atomic configuration:

git add .github
git commit -m "Install reviewed Dependabot operation"
git push --set-upstream origin HEAD

Step 5 - Trigger one review run

Run the installed orchestrator against the target repository:

gh aw run dependabot --ref main \
  --raw-field target_repo="$TARGET_REPO" \
  --raw-field max_repos="1" \
  --raw-field rollout_percent="100" \
  --raw-field safe_output_mode="review"

You can also open the control repository’s Actions tab, select Dependabot, and choose Run workflow with the same values.

The orchestrator should select only the named repository and dispatch at most one updater. In review mode, proposed safe outputs are saved in the private control repository without creating or changing issues, pull requests, branches, or files in the target.

Step 6 - Wait for the operation to complete

List the latest Dependabot runs:

gh run list --workflow dependabot.lock.yml --event workflow_dispatch --limit 5

Copy the run ID from the first row, then watch it until completion:

gh run watch <run-id> --exit-status

The orchestrator may dispatch a separate updater run. Open the orchestrator run in the Actions tab to follow its correlated worker and inspect the review output.

Verify the Result

A successful first run proves the boundary:

• the orchestrator selected exactly TARGET_REPO;
• no more than one updater was dispatched;
• the worker remained in review mode;
• the review output in the control repository links back to the control-plane run;
• no issue, pull request, branch, or file was written to the target repository.

The worker may report that no dependency work is needed. That is still a successful first run when target selection, routing, and zero-write behavior are correct.

Having trouble? Check Configure Authentication for repository access, Configuration for policy fields, or Monitor and Recover for failed runs.

What’s Next?

• Learn how to promote the operation from review to live.
• Read How the Control Plane Works before adding organizations or broader repository discovery.
• Use the Configuration Reference to tune schedules, repository limits, and worker ceilings.
• Review Orchestrators and Workers before creating another operation.