# ACS Bumper

ACS Bumper is an internal tool for TiDB Cloud delivery engineers to safely manage component versions and configuration changes across multiple regions in the `app-delivery` repository in batch. All changes follow a **preview-first, then execute** two-phase workflow, and are submitted as GitHub Pull Requests — never directly modifying the production environment.

## Core Capabilities

| Capability | Description |
|---|---|
| **Image Bump** | Batch upgrade image tags for ACS, Vector, or VMagent |
| **Config Sync** | Propagate verified `config.yaml` changes from a source region to target regions at the YAML path level |
| **Deployment Sync** | Propagate verified `deployment.yaml` changes from a source region to target regions at the YAML path level |

## Architecture Overview

![Architecture](./docs/images/acs-bumper-architecture.svg)

Four-layer architecture, from left to right:

1. **UI Surfaces** — Dashboard, Regions, Bump/Sync operation pages, and operation history
2. **API Boundary** — Next.js App Router API routes, categorized into Read (queries), Preview (dry-run diff), and Execute (SSE streaming execution)
3. **Domain Modules** — Region Scanner, Version Stats, Workflow Core (image strategies + YAML path sync), Guardrails (policy validation + token/hash verification)
4. **Data & Side Effects** — Local `app-delivery` repository read/write, Git CLI operations, GitHub PR creation

## Core Design Principles

- **Preview-first.** All change operations must go through an explicit preview. Users can review full file-level diffs before execution.
- **Diff-only propagation.** Config/Deployment Sync only propagates changed YAML paths — never overwrites entire files — preserving original formatting and comments.
- **Multi-layer safety constraints.** Hash verification prevents TOCTOU race conditions, type change rejection, target conflict detection, and section policy enforcement — multiple layers of protection against production misoperations.

## Three Pipelines

### Image Bump

Select target regions on the Regions page (manually or through built-in gray release presets by architecture) → open Image Bump with that fixed target set → select component → preview tag replacement plan → confirm and execute (sync main → branch → apply → commit → push → PR).

Supports scoping Vector/VMagent changes by section, with strategies determined by both component type and region architecture.

### Config Sync / Deployment Sync

Select target regions on the Regions page → open Config/Deployment Sync with that fixed target set → select the source region → extract path-level diffs from the source file → dry-run against each target → generate preview tokens with hashes → confirm and re-verify hashes before execution.

Config Sync and Deployment Sync share the same two-phase workflow and safety mechanisms, differing only in the target file (`config.yaml` vs `deployment.yaml`).

## Region Model

Regions are auto-discovered based on directory naming conventions — no manifest or database required. Four architectures:

| Architecture | Detection | Key File |
|---|---|---|
| **Dedicated** | Directory structure | `deployment.yaml` |
| **NextGen** | Directory structure | `config.yaml` |
| **Serverless** | `mode: serverless` in `config.yaml` | `config.yaml` |
| **BYOC** | `o11yConfig.isByoc: true` in `config.yaml` | `config.yaml` |

Region IDs are self-descriptive: encoding architecture, provider, environment, and directory name without additional lookups.

## Quick Start

See [`docs/user-guide.md`](docs/user-guide.md) for the complete walkthrough with screenshots and troubleshooting.

### Prerequisites

- Node.js 20+
- `gh` CLI authenticated (`gh auth status`)
- Local clone of the `app-delivery` repository

### Configuration

Create `.env.local` in the project root:

```bash
APP_DELIVERY_REPO_PATH=/absolute/path/to/app-delivery
```

`GITHUB_REPO` is optional, defaults to `tidbcloud/app-delivery`.

Gray release presets live in `config/gray-release.json`. Each `regionIds` entry must use the scanner ID format `<architecture>:<provider>:<environment>:<directory-name>`, for example `nextgen:aws:prod:prod-aws-ap-south-1-ng`.

### Run

```bash
npm install
npm run dev
```

Visit `http://localhost:3210`.