---
name: devops-api
description: |
  Also named Ops Portal, handle software delivery, operations, cluster tasks, and incidents.
  Includes: List, inspect, create, update, and cancel Release Change records; release software;
  Query tenant/cluster information and TiCDC changefeed display-name metadata,
  Query and create incidents, Operate cluster, Manage bastions (alias Jump Service).
---

This skill is the entry point for DevOps System (alias Ops Portal) related requests.
It identifies the user's operational intent, extracts common deployment context,
and routes the task to the most appropriate DevOps sub-skill.

IMPORTANT: All file paths in this skill are relative to the current directory.

# Use this skill when

Use this skill when the user asks about:
- list, inspect, create, update, or cancel a Change on an Ops Portal release page.
- release a service or application.
- query tenant or cluster information.
- query the Ops Portal changefeed list or map a product-facing changefeed name to its numeric TiCDC ID.
- query, inspect, create, or manage TiDB Cloud incidents, timelines, postmortems, and follow-up actions.
- locate the canonical incident severity, SLA, SOP, War Room, and postmortem references.
- operate a cluster (e.g. scale, restart, config change etc).
- manage bastions or jump service access.
- view TiDB tools status (DM, CDC, import, backup, restore) for a cluster.

# Workflow

## Step 1: Discover and select sub-skills

Before selecting a DevOps sub-skill, first read sub-skill index file `SUBSKILLS_INDEX.md`.

This file contains:
- sub-skill name
- sub-skill description
- sub-skill `SUBSKILL.md` path

Find the most relevant sub-skill by matching the user's request against the sub-skill name and description.

## Step 2: Read the selected sub-skill's `SUBSKILL.md` file

Read the `SUBSKILL.md` file of the selected sub-skill to understand its capabilities, required parameters, and usage instructions.

# Step 3: Access DevOps backend API

Build the API request based on the information from the sub-skill. Send the request via the script:

`scripts/devops_http.sh`

More details on how to use this script refer to section "DevOps API Access".

# TiDB Tools — Aggregated Overview

Use this endpoint for the lightweight Tools-page overview:

API Path: `/{cluster_id}/tidbtools/overview`

Method: `GET`

Replace `{cluster_id}` with the numeric cluster ID.

Example:

```bash
./scripts/devops_http.sh --path /123456/tidbtools/overview
```

The controller currently returns at most five rows for each Dedicated-only
section. Changefeeds follow the CDC list behavior documented in the TiCDC
sub-skill and can return up to 1000 rows.

| Cluster type | Sections populated |
|---|---|
| Dedicated | `dm_jobs`, `imports`, `backups`, `log_backups`, `restores`, `changefeeds` |
| Premium | `changefeeds` only |

For Premium DM jobs, prechecks, and IMPORT INTO tasks, use the corresponding
domain sub-skill instead of relying on this overview.

Response shape (`GetOverviewResp`):

| Field | Type | Notes |
|---|---|---|
| `dm_overview` | `DMOverview` | declared by the DTO but currently not populated |
| `dm_jobs` | `ListDMJobsResp` | Dedicated only; omitted on failure or when not applicable |
| `imports` | `ListImportsResp` | Dedicated only; omitted on failure or when not applicable |
| `import_into_tasks` | `ListImportIntoTasksResp` | declared by the DTO but currently not populated |
| `backups` | `ListBackupsResp` | Dedicated only; omitted on failure or when not applicable |
| `log_backups` | `ListLogBackupsResp` | Dedicated only; omitted on failure or when not applicable |
| `restores` | `ListRestoresResp` | Dedicated only; omitted on failure or when not applicable |
| `changefeeds` | `ListChangefeedsOverviewResp` | all supported cluster types; omitted on failure |
| `warnings` | `string[]` | non-fatal per-tool errors; omitted when empty |

`ListChangefeedsOverviewResp` is the overview-specific response type. It has the
same `items` and `total` fields and uses the same `ChangefeedSummary` schema as
the TiCDC sub-skill's `ListChangefeedsResp`.

Fields use `omitempty`: an unavailable section is absent from JSON, not present
with a `null` value. A per-tool failure also omits that section and adds a
`"<tool>: <error>"` entry to `warnings`.

For detailed per-tool operations, route to the appropriate sub-skill via `SUBSKILLS_INDEX.md`.

# Environments

DevOps has three environments. When the user refers to an environment, pass `--env` accordingly:

| Environment | `--env` value | DevOps backend | DevOps frontend |
|---|---|---|---|
| Production | `prod` | `https://prod.devops.pingcap.com` | `https://ops.tidbcloud.com` |
| Staging | `staging` | `https://staging.devops.pingcap.com` | `https://ops-staging.tidbcloud.com` |
| Dev | `dev` | `https://dev.devops.pingcap.com` | `https://ops-dev.tidbcloud.com` |

If the user does not specify an environment, default to **prod**.

When returning a URL to the user (e.g. a change detail link), use the frontend domain for the same environment.

# DevOps API Access

The DevOps backend API can be accessed via the `scripts/devops_http.sh` script, which is a wrapper around `curl` that handles authentication and base domain resolution.

```bash
Usage:
  devops_http.sh --path /api/path [--env prod|staging|dev] \
    [--method METHOD] \
    [--query "k=v&x=y"] \
    [--body '{"a":"b"}' | --body-file /path/to/body.json] \
    [--header "Key: Value"] \
    [--timeout 30]

Required:
  --path    HTTP path (without /api/v1/devops prefix), e.g. /cloudconfig/cluster/config

Optional:
  --env       Target environment: prod (default), staging, dev
  --method    HTTP method, default: GET
  --query     Raw query string
  --body      Raw request body (JSON)
  --body-file Read request body from file
  --header    Extra HTTP header, repeatable
  --timeout   Curl timeout in seconds, default: 30
  --env-file  Path to .env file, default: .env

Authentication:
  DEVOPS_API_TOKEN must be set in .env or as an environment variable.

Examples:
  ./devops_http.sh --path /cloudconfig/cluster/config \
    --query "cluster_id=xxx&cluster_type=DEDICATED_TIDB"

  ./devops_http.sh --env staging --method POST --path /cloudconfig/cluster/changes \
    --body '{"cluster_type":"DEDICATED_TIDB","cluster_id":"xxx"}'

  ./devops_http.sh --env dev --method POST --path /cloudconfig/changes/123/apply \
    --body '{}'

  ./devops_http.sh --method POST --path /cloudconfig/cluster/changes \
    --body-file ./payload.json

  ./devops_http.sh --method POST --path /cloudconfig/cluster/changes \
    --body-file ./payload.json \
    --header "X-Request-ID: req-123"
```