| 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:
- 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.
