# Agent Playbook

## Agent CLI Flow

This section describes how an agent should close the loop without human navigation in GitHub UI.

## Required tool access

The agent needs terminal access to:

- `git`
- `gh`
- a text editor or patch tool
- `kubectl`
- cloud CLIs when cluster checks are required:
  - `aws`
  - `gcloud`
  - `az`

## Agent contract

When asked to release one or more `dev` or `prod` components, the agent should:

1. Inspect the repo and the relevant previous state for the target environment.
2. Confirm which component set is in scope:
   - global
   - regional
   - OTel pipeline
   - Prometheus pipeline
   - full dev release
   - full prod release
3. Determine the target SHA:
   - dev release: the requested commit SHA, usually from `main`
   - prod normal release: the tagged commit SHA
   - prod hotfix release: the hotfix branch HEAD SHA
4. Trigger or wait for the correct image build workflow.
5. Update the correct manifest files in git.
6. Open a PR with `gh pr create`.
7. Merge with `gh pr merge` when the repo policy allows it.
8. Run deploy workflows from `main` using `gh workflow run`.
9. Watch the runs with `gh run watch`.
10. Perform minimum environment-appropriate checks with `kubectl`.
11. Report exactly what changed, which workflow runs were used, and what still requires human approval.

## Agent playbook by request type

### Request: "Release global dev"

The agent should:

1. Resolve the target SHA.
2. Ensure `dev-ci-global.yaml` produced `tidbcloud/metrics-integration-global:${SHA}`.
3. Patch `global/deployment/kustomize/envs/dev/kustomization.yaml`.
4. Open and merge the PR.
5. Run `universal-deploy-global.yaml` with:
   - `env=dev`
   - `use_apply=false`
   - then `use_apply=true`

### Request: "Release regional dev"

The agent should:

1. Ensure `dev-ci-regional.yaml` built the target image.
2. Patch the three regional dev kustomization files.
3. Open and merge the PR.
4. Run `dev-deploy-regional.yaml` with diff first, then apply.
5. Explicitly report that the workflow currently deploys AWS dev `us-west-2` only.

### Request: "Release OTel pipeline dev"

The agent should:

1. Ensure `dev-ci-pipeline.yaml` built the target image.
2. Patch `global/deployment/kustomize/envs/dev/configmap.yaml` and update only the pipeline `imageTag`.
3. Open and merge the PR.
4. Run `universal-deploy-global.yaml` with `env=dev`, diff first, then apply.
5. If immediate live collector rollout is in scope, reconcile or roll the collector workloads and report what was updated.

### Request: "Release Prometheus dev"

The agent should:

1. Ensure `dev-ci-prometheus.yaml` built the target image.
2. Patch the three dev Prometheus cloud-variant kustomization files.
3. Open and merge the PR.
4. Run `dev-deploy-prometheus-regional.yaml` with diff first, then apply.
5. Explicitly report that the workflow currently deploys AWS dev `us-west-2` only.

### Request: "Release global prod"

The agent should:

1. Resolve the target SHA.
2. Ensure `prod-ci-global.yaml` produced `tidbcloud/metrics-integration-global:${SHA}`.
3. Patch `global/deployment/kustomize/envs/prod/kustomization.yaml`.
4. Open and merge the PR.
5. Run `universal-deploy-global.yaml` with:
   - `env=prod`
   - `use_apply=false`
   - then `use_apply=true`
6. Check rollout status in `prod-ms`.

### Request: "Release regional prod"

The agent should:

1. Ensure `prod-ci-regional.yaml` built the AWS image.
2. Run `universal-sync-multicloud-image.yaml` for GCP and Azure.
3. Patch the three regional prod kustomization files.
4. Open and merge the PR.
5. Run `prod-deploy-regional.yaml` with diff first, then apply.
6. Check that the regional service is healthy in representative clusters.

### Request: "Release OTel pipeline prod"

The agent should:

1. Ensure `prod-ci-pipeline.yaml` built the AWS image.
2. Run `universal-sync-multicloud-image.yaml` for GCP and Azure.
3. Patch `global/deployment/kustomize/envs/prod/configmap.yaml` and update only the pipeline `imageTag` for a normal release.
4. Open and merge the PR.
5. Run `universal-deploy-global.yaml` with diff first, then apply.
6. If the request includes immediate live collector rollout, run `kubectl set image` for existing pipeline collector deployments and wait for rollout completion.

### Request: "Release Prometheus prod"

The agent should:

1. Ensure `prod-ci-prometheus.yaml` built the target image.
   For a normal release, it should come from the release tag automatically.
   For a hotfix or rerun, use `workflow_dispatch` at the hotfix branch or release tag.
2. Run `universal-sync-multicloud-image.yaml` for GCP and Azure.
3. Patch the three Prometheus cloud-variant kustomization files.
4. Open and merge the PR.
5. Run `prod-deploy-prometheus-regional.yaml` with diff first, then apply.
6. Check rollout status in `prometheus-integration`.

## Definition of Done for an Agent

The release is only done when all of the following are true:

- the required build workflow succeeded
- the required image tag was written into the correct manifest files
- the PR was created and merged, or the agent clearly reports why it could not merge
- the deploy workflow was run in diff mode and apply mode
- the main workload rollout succeeded in cluster
- any manual collector image updates requested in scope were completed
- the final report includes:
  - target environment
  - target SHA
  - changed files
  - workflow names used
  - run IDs or run URLs
  - remaining risks or follow-up actions