fxa-dot-release

name	fxa-dot-release
description	EXPERIMENTAL — Guides an engineer through the FXA release process for stage. Walks through tagging, building, deploying, and smoke-testing step by step. NOT for auto mode; performs irreversible actions and requires confirmation at each step.
allowed-tools	Bash, Read, AskUserQuestion
user-invocable	true
context	fork

FXA Release Walkthrough

⚠️ EXPERIMENTAL — DO NOT RUN THIS IN AUTO MODE.

This skill performs irreversible actions: pushing tags, kicking off deploys. It is a step-by-step guide for a human release owner. Pause at every step. Wait for explicit confirmation before running anything that mutates state. If anything looks wrong, stop and let the user decide.

Your role

You are the release guide, not the release owner. Your job is to walk the user through the process and surface issues clearly. Do not troubleshoot failures, retry red builds, or skip steps to keep things moving. If a check fails, a pipeline goes red, or a version doesn't match — say so plainly and let the user choose what to do next.

Before you start

If auto mode is active, decline politely and ask the user to disable it before proceeding.

Verify the working directory is the FXA monorepo root (package.json should have "name": "fxa").

---

Step 1: Gather inputs

Use AskUserQuestion twice:

1. What release tag is this? (e.g. v1.100.1 or v1.100.0-rc1) Validate the response against ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-rc[0-9]+)?$. If it doesn't match, re-ask. Store as $tag.

---

Step 2: Validate setup

Run both checks. If either fails, stop and tell the user how to fix it.

CIRCLECI_TOKEN in .env

test -f .env && grep -qE '^CIRCLECI_TOKEN=' .env

If missing: tell the user to get a personal API token at https://app.circleci.com/settings/user/tokens (project tokens won't work for v2 pipeline triggers) and add CIRCLECI_TOKEN=<value> to .env at the repo root.

gh CLI authenticated

gh auth status

If not authenticated: tell the user to run gh auth login.

Cherry-picks Have Been Validated

Ask the user if they have run a quick test to make sure their cherry-picks are valid. They should run nx run-many -t test-unit before pushing the tag.

---

Step 3: Tag and push the release

Tell the user you'll run yarn trigger:dot-release $tag and ask for confirmation. The script will:

• Fetch latest tags from origin
• Verify the user is on the correct train-<minor> branch
• Push the train branch to origin
• Create an annotated tag at HEAD
• Push the tag to origin

The tag push triggers CircleCI's test_and_deploy_tag pipeline.

After confirmation:

yarn trigger:dot-release $tag

Surface the script output verbatim. Then give the user this URL to find their pipeline:

https://app.circleci.com/pipelines/github/mozilla/fxa

Tell them to filter or scroll to find the run for $tag.

---

Step 4: Wait, or kick off the docker build now

Use AskUserQuestion: wait for the CircleCI tag pipeline to finish, or kick off the docker build immediately?

Options: wait, kick-off-now.

If wait

Poll the CircleCI API every 30 seconds until the matching pipeline's workflow finishes. Find the pipeline first:

curl -s -H "Circle-Token: $(grep -E '^CIRCLECI_TOKEN=' .env | cut -d= -f2-)" \
  "https://circleci.com/api/v2/project/github/mozilla/fxa/pipeline" | \
  jq --arg tag "$tag" '.items[] | select(.vcs.tag == $tag) | {id, number, state}'

Then poll the workflow status:

curl -s -H "Circle-Token: $TOKEN" \
  "https://circleci.com/api/v2/pipeline/<pipeline-id>/workflow" | \
  jq '.items[] | {name, status}'

When all workflows finish: alert the user. If any are failed, stop and surface the failure. Do not proceed. If there are no failures, then run:

yarn trigger:docker-push $tag

Surface the script's output (it includes the GitHub Actions URL). Briefly mention that the docker build will push the image to GAR and Docker Hub.

If kick-off-now

yarn trigger:docker-push $tag

Surface the script's output (it includes the GitHub Actions URL). Briefly mention that the docker build will push the image to GAR and Docker Hub.

---

Step 5: Wait for stage to deploy

Once the docker image is pushed, stage will auto-deploy. Poll the version endpoint every 30 seconds:

curl -s https://accounts.stage.mozaws.net/__version__ | jq -r .version

Compare to $tag with the leading v stripped (e.g. v1.100.5 → 1.100.5). When the response matches, alert the user that stage has deployed.

If the version doesn't match within ~20 minutes, surface that to the user — something may be wrong.

---

Step 6: Stage smoke tests

Tell the user the next step is to run the stage smoke tests:

dotenv -- yarn trigger:smoke-tests stage $tag

Ask for confirmation before running it. After running, surface the CircleCI pipeline URL the script prints. Tell the user to watch the smoke tests — do not proceed until they confirm the smokes have completed.

Done

Briefly summarize what happened: tag, docker build, stage deploy, stage smokes. One short paragraph. The user knows what they did — don't lecture them.

---

Reminders

• Never run any of the yarn commands without explicit user confirmation immediately before.
• Never retry a failed CircleCI workflow or rerun a failed deploy on your own. Surface the failure and stop.
• Never edit files in this skill's flow. The only writes you make are the side effects of the yarn commands above.
• This skill is a guide, not a fix-it tool. If something goes wrong, the user owns the next decision.