Gpc Train

GPC Release Train

When to use

Use this skill when the task involves:

• Setting up a config-driven staged rollout pipeline
• Automatically progressing a release through tracks (internal → alpha → production) with time gates
• Gating progression on crash rate and ANR rate thresholds
• Pausing, resuming, or aborting an in-flight release train
• Checking the current stage and gate health of a running train

Inputs required

• Package name (or configured default in .gpcrc.json)
• Release train config: stages with tracks, rollout percentages, and time delays
• Gate thresholds: max crash rate and max ANR rate
• Whether to pause, resume, or abort the train

Procedure

1) Configure the release train

Add a release-train block to .gpcrc.json in the project root:

{
  "release-train": {
    "stages": [
      { "track": "internal",   "rollout": 100 },
      { "track": "alpha",      "rollout": 100, "after": "2d" },
      { "track": "production", "rollout": 10,  "after": "7d" },
      { "track": "production", "rollout": 100, "after": "14d" }
    ],
    "gates": { "crashes": { "max": 1.5 }, "anr": { "max": 0.5 } }
  }
}

Config keys:

Read:

• references/rollout-pipeline.md

2) Start the train

gpc train start

This reads .gpcrc.json, creates a state file at ~/.cache/gpc/train-<packageName>.json, and begins executing the first stage immediately. Subsequent stages are executed when the after time has elapsed and gates pass.

# Resume a paused train
gpc train start --resume

3) Check train status

gpc train status

Output:

Release Train · com.example.app
  Stage 2 / 4   alpha @ 100%   in progress
  Last progressed: 2026-03-17 11:00 (2 days ago)
  Next stage: production @ 10%   eligible in 5 days

  Gates (last check: 10 minutes ago)
    crashes   0.82%   ✓  (max 1.5%)
    anr       0.19%   ✓  (max 0.5%)

# Resume if paused due to a gate failure
gpc train status --resume

4) Monitor gate health

Before each stage transition, gpc train automatically checks the configured gates:

• If all gates pass, the stage progresses (subject to the after time having elapsed).
• If any gate fails, progression is paused and a warning is shown.
• The user must fix the regression and re-run gpc train start --resume or gpc train status --resume.

Gate checks call the same vitals API as gpc vitals crashes and gpc vitals anr. Data lag of 6–48 hours applies to new releases — avoid configuring gates on the very first stage.

5) Pause a running train

gpc train pause

Pauses automatic progression. Does not halt or change the active rollout on any track. Run gpc train start --resume to continue.

6) Abort the train

gpc train abort

Aborts the train and halts all active rollouts on tracks managed by this train. State file is cleared. Use when a critical regression is found and the release must be stopped immediately.

Verification

• gpc train status shows the correct current stage and gate health values
• gpc status confirms rollout percentages on each track match the active stage in the train config
• Gate values (crashes, ANR) are below configured max thresholds
• State file at ~/.cache/gpc/train-<packageName>.json reflects the current stage index and last progression timestamp

Failure modes / debugging

Read:

• references/rollout-pipeline.md — full lifecycle: config → start → gate check → progress → complete

Related skills

• gpc-release-flow: Upload, promote, and manual rollout management
• gpc-vitals-monitoring: Crash and ANR monitoring used by gate checks
• gpc-ci-integration: Running gpc train in CI/CD pipelines

Release Train — Full Lifecycle

End-to-end reference for the gpc train config-driven staged rollout pipeline.

Overview

configure .gpcrc.json → gpc train start → stage 1 (immediate)
  → [wait: after time] → gate check → stage 2
  → [wait: after time] → gate check → stage 3
  → [wait: after time] → gate check → stage 4 → complete

Each stage transition requires two conditions to be met: 1. The after time delay has elapsed since the previous stage. 2. All configured gates (crash rate, ANR rate) are below their max thresholds.

If either condition fails, progression is paused until the issue is resolved and the user resumes.

State file

The train stores its progress in:

~/.cache/gpc/train-<packageName>.json

Example state:

{
  "packageName": "com.example.app",
  "startedAt": "2026-03-15T10:00:00Z",
  "currentStageIndex": 2,
  "lastProgressedAt": "2026-03-17T10:05:00Z",
  "status": "running",
  "gateFailures": []
}

Status values: running, paused, aborted, complete.

Config reference

{
  "release-train": {
    "stages": [
      { "track": "internal",   "rollout": 100 },
      { "track": "alpha",      "rollout": 100, "after": "2d" },
      { "track": "production", "rollout": 10,  "after": "7d" },
      { "track": "production", "rollout": 100, "after": "14d" }
    ],
    "gates": {
      "crashes": { "max": 1.5 },
      "anr":     { "max": 0.5 }
    }
  }
}

Time format for after

Omitting after means the stage is eligible immediately (subject to gate checks still passing).

Phase-by-phase lifecycle

Phase 1 — Config

Create or update .gpcrc.json with the release-train block. This is the single source of truth for stage definitions and gate thresholds. Commit this file to source control so all team members and CI share the same pipeline definition.

Phase 2 — Start

gpc train start

• Reads .gpcrc.json.
• Creates the state file at ~/.cache/gpc/train-<packageName>.json.
• Executes stage 0 immediately (no after delay, no gate check on the first stage).
• Transitions: promotes the release to the configured track at the configured rollout percentage.
• Logs the start timestamp to the state file.

Phase 3 — Gate check

Before each stage transition (stages 1+), gpc train evaluates the configured gates:

crash rate  ≤  gates.crashes.max  →  pass
ANR rate    ≤  gates.anr.max      →  pass

If both pass and the after time has elapsed, progression continues. If either fails, the state is set to paused and a warning is printed:

Gate failed: crash rate 2.1% exceeds max 1.5%
Progression paused. Fix the regression and run: gpc train start --resume

The gate check uses the same vitals API as gpc vitals crashes and gpc vitals anr. Note that vitals data for a newly released version takes 6–48 hours to populate — configure your after delays accordingly.

Phase 4 — Progression

When both conditions are met (time elapsed + gates pass), the train:

1. Calls the appropriate GPC release command for the next stage (promote, rollout increase, or rollout complete). 2. Updates currentStageIndex and lastProgressedAt in the state file. 3. Prints a progress line showing the new stage.

Phase 5 — Complete

When the final stage is executed successfully, the state file status is set to complete and the train exits cleanly:

Release train complete. All stages executed.
  internal → alpha → production@10% → production@100%

Commands at a glance

Pause vs abort

Use pause when you want to temporarily hold the pipeline (e.g., over a holiday weekend) without touching the active rollout.

Use abort when a critical regression requires immediately stopping distribution and starting over.

Gate failure recovery flow

1. gpc train status         → confirm gate failure and which metric
2. gpc vitals crashes       → inspect crash rate and top clusters
3. gpc vitals anr           → inspect ANR rate
4. Fix the regression       → ship a new build to internal
5. gpc train start --resume → resume from the paused stage

If the fix requires a brand-new release (new version code), abort the current train and start a new one:

gpc train abort
# ... upload new AAB, set release notes ...
gpc train start

CI usage

Run the train check in CI to assert that a train is healthy before a deployment step:

- name: Check train gate health
  run: gpc train status
  # Exits non-zero if the train is in a failed/aborted state

Or start and detach (fire-and-forget) in an async CI pipeline:

- name: Start release train
  run: gpc train start

The train state persists in ~/.cache/gpc/ — use a persistent cache volume if running across CI jobs.

Timing reference

Set after delays that are long enough for meaningful vitals data to accumulate before gate checks run. A minimum of 2d on any production stage is recommended.