---
name: tcms-devbuild-rebuild
description: |
  Clone an existing PingCAP TCMS devbuild while preserving hidden build fields, override repository, git ref, version, product, or build options, and poll to a terminal image result through an authenticated Chrome or Chromium profile. Use for PD, TiKV, CSE, TiDB, and other TCMS devbuild requests, especially when the new-build page omits effective fields such as githubRepo, a fork branch is rejected, or a teammate needs the final build id, Jenkins id, git hash, and image URLs.
---

# TCMS Devbuild Rebuild

Use the bundled script to clone a known TCMS devbuild specification. Preserve the base specification by default and override only requested fields.

## Preconditions

- Use a Chrome or Chromium profile that is already signed in to `tcms.pingcap.net`.
- Start from a successful base build for the same component and build mode.
- Confirm the requested PR, branch, tag, or commit exists in the target GitHub repository.
- Use Node.js 22 or newer because the script uses the built-in Fetch and WebSocket APIs.

The base build determines the component. The same workflow supports PD, TiKV, CSE, TiDB, and other products represented by TCMS devbuild specifications.

## Workflow

1. Select a successful base build whose hidden fields, architecture, edition, and build environment match the requested output.
2. Verify the remote ref before submitting. For a branch or tag, run `git ls-remote` against the target repository. If TCMS rejects a valid branch, retry with the exact commit SHA.
3. Run a dry run. Check `product`, `githubRepo`, `gitRef`, `version`, `edition`, `buildEnv`, `features`, and `isPushGCR` in the computed payload.
4. Create the build and keep polling until a terminal status. The default interval is 180 seconds and the default timeout is 40 polls.
5. Report the terminal status, TCMS build id, Jenkins build id, resolved git hash, and every image URL returned by TCMS.
6. If another person owns rollout or testing, send the final image to that person as soon as the build reaches a terminal state.

## Commands

Dry-run a rebuild without creating anything:

```bash
node scripts/tcms_devbuild_rebuild.mjs \
  --base-build <base-build-id> \
  --github-repo <owner/repository> \
  --git-ref <pull/ref-or-commit> \
  --dry-run
```

Create the build and poll to completion:

```bash
node scripts/tcms_devbuild_rebuild.mjs \
  --base-build <base-build-id> \
  --github-repo <owner/repository> \
  --git-ref <pull/ref-or-commit> \
  --poll
```

Override additional fields only when the request requires them:

```bash
node scripts/tcms_devbuild_rebuild.mjs \
  --base-build <base-build-id> \
  --git-ref <commit-sha> \
  --version <version-label> \
  --product <product> \
  --edition <edition> \
  --features <features> \
  --build-env <build-environment> \
  --push-gcr true \
  --poll
```

Use `--json` for structured output. Use `--no-poll` only when the user explicitly asks to submit without monitoring.

## Browser Selection

The script copies the selected browser profile into an operating-system temporary directory, removes stale browser lock files, uses the copied TCMS session, and deletes the copy on exit. It does not modify the live profile.

It auto-detects common Chrome and Chromium binaries and profile roots. Override discovery when needed:

```bash
node scripts/tcms_devbuild_rebuild.mjs \
  --base-build <base-build-id> \
  --browser-bin <browser-executable> \
  --browser-profile <browser-profile-root> \
  --profile-directory <profile-directory> \
  --dry-run
```

Equivalent environment variables are `TCMS_BROWSER_BIN`, `TCMS_BROWSER_PROFILE`, `TCMS_PROFILE_DIRECTORY`, `TCMS_BASE_URL`, and `TCMS_JENKINS_URL`.

## Failure Handling

- For `gitRef is not valid`, verify the ref with `git ls-remote`. If it exists, submit the exact commit SHA.
- For missing TCMS authentication, open the selected profile in Chrome or Chromium, sign in to TCMS, close the browser cleanly, and retry.
- For a terminal build failure, use the redacted Jenkins console tail printed by the script to identify the first actionable cause.
- For a polling timeout, report the created build id and last observed status. Do not describe a nonterminal build as successful.
- If the new-build page and cloned build behave differently, compare the base and computed `spec`, especially `githubRepo`, `product`, `buildEnv`, `edition`, and `features`.

## Security

- Never print or share the TCMS bearer token. The script reads it from browser-local state and keeps it in memory.
- Do not commit copied browser profiles, dry-run payloads, or console logs.
- Inspect output before posting it outside the authorized internal channel. Build metadata and image registries may be internal.

## Completion Criteria

Finish only after reporting:

- base build id
- new TCMS build id
- Jenkins build id
- terminal status
- resolved git hash
- final image URL or URLs

When the build fails, replace the image handoff with the shortest redacted log excerpt that identifies the failure.