Auto Deploy Esperanto Review App

/auto-deploy-esperanto-review-app — Automate Esperanto Review App Deployment

Purpose

Automates the deployment of HPP review versions to Esperanto QA stage environment. When an HPP PR with label 'qa-required' publishes a review version (e.g., "3.0.130-074e20d"), this skill extracts that version and creates/updates an Esperanto PR for QA testing.

What it does:

1. Auto-detects current HPP PR (from branch or user argument)
2. Fetches HPP PR details (branch name, title, and labels)
3. Validates PR has 'qa-required' label
4. Extracts review version from PR comments
5. Checks out Esperanto repository
6. Creates/updates branch in Esperanto using HPP PR's branch name
7. Updates package.json with yarn add @kroger/hosted-payment-page@VERSION
8. Commits and pushes changes
9. Creates new Esperanto PR with "[Payments] " + HPP PR title OR updates existing PR
10. Adds labels: "Autodeploy Stage Review App", "version-minor"
11. Comments back on HPP PR with Esperanto PR link

Type: Standalone coordinator (spawns general-purpose sub-agent)

Usage

From HPP Repo

# Provide the HPP PR number as argument
cd <path-to-hosted-payment-page-repo>
/auto-deploy-esperanto-review-app <PR-NUMBER>

# Example:
/auto-deploy-esperanto-review-app 328

Note: PR number is required. You can find it in the PR URL or by running git branch --show-current and checking GitHub.

Prerequisites

Required:

• GitHub MCP server configured (for PR operations)
• yarn installed (for package updates)
• HPP and Esperanto repos cloned as sibling directories (same parent folder)
• HPP PR must have:
  • Label: 'qa-required'
  • Comment matching: "A review version has been published: X.Y.Z-COMMIT"

Validation:

# Check GitHub MCP
grep -q "github" ~/.claude/mcp.json || echo "❌ GitHub MCP not configured"

# Check yarn
command -v yarn || echo "❌ yarn not installed"

# Verify we're in HPP repo
git remote get-url origin | grep -q "hosted-payment-page" || echo "❌ Not in HPP repo"

Instructions

You are the coordinator for the /auto-deploy-esperanto-review-app skill. Follow the coordinator-agent pattern:

1. Validate prerequisites
2. Get HPP PR number
3. Spawn sub-agent to execute deployment
4. Report results to user
5. NEVER retry sub-agent work - report failures to user

Step 1: Validate Prerequisites

Check required tools and GitHub MCP:

1. Validate GitHub MCP is available:

   • Use ToolSearch to check if mcp__github__pull_request_read is available
   • If not available: ERROR "GitHub MCP not configured. Check ~/.claude/mcp.json"

2. Validate yarn is installed:

   if ! command -v yarn &> /dev/null; then
     echo "❌ yarn not found. Install: npm install -g yarn"
     exit 1
   fi
   

3. Validate git repo and we're in HPP repo:

   REMOTE_URL=$(git remote get-url origin 2>/dev/null)
   if [ -z "$REMOTE_URL" ]; then
     echo "❌ Not in a git repository"
     exit 1
   fi
   
   REPO_SLUG=$(echo "$REMOTE_URL" | sed 's/.*[:/]\([^/]*\/[^/]*\)\.git/\1/' | sed 's/.*[:/]\([^/]*\/[^/]*\)$/\1/')
   if [ "$REPO_SLUG" != "krogertechnology/hosted-payment-page" ]; then
     echo "❌ Must run from hosted-payment-page repo, found: $REPO_SLUG"
     exit 1
   fi
   

Step 2: Get HPP PR Number

Extract PR number from user argument or ask:

If user provided PR number as argument:

• Use it directly
• Validate it's numeric

If no argument provided:

• Use AskUserQuestion to get the PR number:
  • Question: "What is the HPP PR number to deploy?"
  • Header: "HPP PR"
  • Options: This should be a text input, but since AskUserQuestion requires options, use a single option "Enter PR number" and the user can provide custom input via "Other"
  • Alternatively, just ask the user to provide the PR number as an error message

Simpler approach: If no argument provided, show error asking for PR number:

If no argument:
  echo "❌ HPP PR number required"
  echo "Usage: /auto-deploy-esperanto-review-app <HPP-PR-NUMBER>"
  exit 1

Validate PR number is numeric:

if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
  echo "❌ Invalid PR number: $PR_NUMBER (must be numeric)"
  exit 1
fi

Store: PR_NUMBER

Step 3: Determine Esperanto Repo Path

Find Esperanto repo location:

# We're in HPP - find sibling Esperanto repo
HPP_PATH=$(pwd)
PARENT_DIR=$(dirname "$HPP_PATH")
ESPERANTO_PATH="${PARENT_DIR}/esperanto"

if [ ! -d "$ESPERANTO_PATH/.git" ]; then
  echo "❌ Esperanto repo not found at: $ESPERANTO_PATH"
  echo "Expected repos to be siblings in: $PARENT_DIR"
  echo "Clone esperanto: gh repo clone krogertechnology/esperanto $ESPERANTO_PATH"
  exit 1
fi

echo "Found Esperanto repo: $ESPERANTO_PATH"

Step 4: Spawn Deployment Sub-Agent

Use the Task tool to spawn a general-purpose sub-agent that executes the deployment workflow:

Task Configuration:

subagent_type: "general-purpose"
description: "Deploy HPP review app to Esperanto"
model: "sonnet"  # Complex workflow with multiple git operations

Sub-Agent Prompt:

Deploy Hosted Payment Page review version to Esperanto QA stage environment.

## CONTEXT

- **HPP PR Number**: <PR_NUMBER>
- **Esperanto Path**: <ESPERANTO_PATH>
- **HPP Repo**: krogertechnology/hosted-payment-page
- **Esperanto Repo**: krogertechnology/esperanto

## TASKS

Execute the following tasks in sequence. On ANY error, stop immediately and report the failure.

### Task 1: Fetch HPP PR Details

Use GitHub MCP to load the tool first, then fetch PR details:

ToolSearch: "select:mcp__github__pull_request_read"

Then use `mcp__github__pull_request_read`:

owner: "krogertechnology" repo: "hosted-payment-page" pullNumber: method: "get"

Extract from the response:
- **Branch name** (head.ref): The source branch name of the HPP PR
- **PR title**: The title of the HPP PR
- **Labels**: Array of label objects

Store these:
- HPP_BRANCH_NAME
- HPP_PR_TITLE

**Validate 'qa-required' label**:
- Check if labels array contains an object with name: "qa-required"
- If NOT found: ERROR "HPP PR #<PR_NUMBER> does not have 'qa-required' label. Add the label and try again."

### Task 2: Fetch HPP PR Comments

Use `mcp__github__pull_request_read` to get PR comments:

owner: "krogertechnology" repo: "hosted-payment-page" pullNumber: method: "get_comments"

### Task 3: Extract Review Version

Search comments (in reverse order, most recent first) for version pattern:
- **Pattern**: `A review version has been published: (\d+\.\d+\.\d+-[a-f0-9]+)`
- **Example**: "A review version has been published: 3.0.130-074e20d"
- Extract the version string (e.g., "3.0.130-074e20d")

**Error Handling**:
- If no match found: ERROR "No review version comment found in HPP PR #<PR_NUMBER>. Ensure PR has 'qa-required' label and version has been published."
- If multiple matches: Use the MOST RECENT comment (first match when searching in reverse)

Store: REVIEW_VERSION

### Task 4: Check for Existing Esperanto PR

Use GitHub MCP to check if an Esperanto PR already exists for this branch:

ToolSearch: "select:mcp__github__list_pull_requests"

Then use `mcp__github__list_pull_requests`:

owner: "krogertechnology" repo: "esperanto" state: "open" head: "krogertechnology:" base: "main"

If a PR is found:
- Store: ESPERANTO_PR_EXISTS=true
- Store: ESPERANTO_PR_NUMBER (from response)
- Store: ESPERANTO_PR_URL (html_url from response)
- Log: "Found existing Esperanto PR #<ESPERANTO_PR_NUMBER>"

If no PR found:
- Store: ESPERANTO_PR_EXISTS=false
- Log: "No existing Esperanto PR found, will create new"

### Task 5: Setup Esperanto Branch

```bash
cd <ESPERANTO_PATH>

# Ensure on main and up to date
git fetch origin
git checkout main
git pull origin main

# Check if branch exists remotely
if git ls-remote --heads origin "<HPP_BRANCH_NAME>" | grep -q "<HPP_BRANCH_NAME>"; then
  echo "Branch exists remotely, checking out"
  git fetch origin "<HPP_BRANCH_NAME>"
  git checkout "<HPP_BRANCH_NAME>"
  # Pull latest changes
  git pull origin "<HPP_BRANCH_NAME>"
else
  echo "Creating new branch from main"
  git checkout -b "<HPP_BRANCH_NAME>"
fi

echo "✓ On branch: <HPP_BRANCH_NAME>"

Task 6: Update package.json

Use yarn to update the HPP dependency:

cd <ESPERANTO_PATH>

# Update @kroger/hosted-payment-page to review version
yarn add @kroger/hosted-payment-page@"<REVIEW_VERSION>"

YARN_EXIT=$?

if [ $YARN_EXIT -ne 0 ]; then
  echo "❌ yarn add failed with exit code: $YARN_EXIT"
  exit 1
fi

echo "✓ Updated @kroger/hosted-payment-page to <REVIEW_VERSION>"

# Verify the update
grep "@kroger/hosted-payment-page" package.json

Expected Changes:

• package.json should be updated with the new version
• yarn.lock will be updated

Task 7: Verify Changes

cd <ESPERANTO_PATH>

# Check git status
CHANGED_FILES=$(git status --porcelain | wc -l)

if [ $CHANGED_FILES -eq 0 ]; then
  echo "⚠️  No files changed - version may already be deployed"
  echo "Current version in package.json:"
  grep "@kroger/hosted-payment-page" package.json

  # If Esperanto PR exists, we should still comment on HPP PR
  # If no PR exists, we can skip
  if [ "$ESPERANTO_PR_EXISTS" = "false" ]; then
    echo "Skipping - no changes needed"
    exit 0
  fi
else
  echo "✓ Verified file changes"
  git status --short
fi

Task 8: Commit and Push Changes (Only if changes exist)

cd <ESPERANTO_PATH>

# Only commit if there are changes
if [ $CHANGED_FILES -gt 0 ]; then
  # Stage all changes
  git add -A

  # Create commit message
  COMMIT_MSG="chore: update @kroger/hosted-payment-page to <REVIEW_VERSION>

Automated deployment from HPP PR #<PR_NUMBER>
Review version: <REVIEW_VERSION>

Related: krogertechnology/hosted-payment-page#<PR_NUMBER>"

  git commit -m "$COMMIT_MSG"

  # Push branch
  git push -u origin "<HPP_BRANCH_NAME>"

  echo "✓ Committed and pushed changes"
fi

Task 9: Create or Update Esperanto PR

If ESPERANTO_PR_EXISTS = false (Create new PR):

Use GitHub MCP to create PR:

ToolSearch: "select:mcp__github__create_pull_request"

Then use mcp__github__create_pull_request:

owner: "krogertechnology"
repo: "esperanto"
head: "<HPP_BRANCH_NAME>"
base: "main"
title: "[Payments] <HPP_PR_TITLE>"
body: "## WHPP Review Version Update

This PR updates the `@kroger/hosted-payment-page` dependency to review version **<REVIEW_VERSION>**.

**Related WHPP PR**: krogertechnology/hosted-payment-page#<PR_NUMBER>

---
_Auto-generated by auto-deploy-esperanto-review-app skill_"
draft: false

Store the response:

• ESPERANTO_PR_NUMBER (number from response)
• ESPERANTO_PR_URL (html_url from response)

Add Labels:

Try to add labels, but don't fail if it doesn't work:

1. Load the label tool:

   ToolSearch: "select:mcp__github__issue_write"
   

2. Use mcp__github__issue_write with method "add_labels":

   {
     "owner": "krogertechnology",
     "repo": "esperanto",
     "issueNumber": <ESPERANTO_PR_NUMBER>,
     "method": "add_labels",
     "labels": ["Autodeploy Stage Review App", "version-minor"]
   }
   

3. Track the result:

   • If successful: Set LABELS_ADDED="YES"
   • If failed: Set LABELS_ADDED="NO (labels may not exist in Esperanto repo)"
   • Log the error but continue (don't exit)

Important: Label addition is optional - if it fails, the deployment still succeeded. User can add labels manually.

If ESPERANTO_PR_EXISTS = true (Update existing PR):

The push already updated the PR with new commits. Just log:

echo "✓ Existing Esperanto PR #<ESPERANTO_PR_NUMBER> updated with new review version"

Task 10: Comment on HPP PR

Create a comment on the original HPP PR with deployment status:

Use mcp__github__add_issue_comment:

owner: "krogertechnology"
repo: "hosted-payment-page"
issueNumber: <PR_NUMBER>
body: "<EMOJI> **Esperanto Review App Deployment**

Esperanto PR has been **<ACTION>** with review version `<REVIEW_VERSION>`

**Esperanto PR**: [#<ESPERANTO_PR_NUMBER>](<ESPERANTO_PR_URL>)

_Auto-generated by auto-deploy-esperanto-review-app skill_"

Where:

• EMOJI: "🚀" if new PR, "🔄" if updated existing PR
• ACTION: "created" if new PR, "updated" if existing PR

Task 11: Report Success

Display results in formatted output:

✓ Esperanto Review App Deployment Complete

| Field | Value |
|-------|-------|
| HPP PR | #<PR_NUMBER> |
| HPP PR Title | <HPP_PR_TITLE> |
| Review Version | <REVIEW_VERSION> |
| Branch | <HPP_BRANCH_NAME> |
| Esperanto PR | #<ESPERANTO_PR_NUMBER> |
| Esperanto PR Title | [Payments] <HPP_PR_TITLE> |
| Status | <CREATED or UPDATED> |
| Labels Added | <YES or NO (with reason if failed)> |

**Esperanto PR URL**: <ESPERANTO_PR_URL>

**Next Steps**:
- Monitor Esperanto PR CI/CD checks for autodeploy to stage
- QA testing can begin once deployed
- Comment added to HPP PR with Esperanto PR link
- If labels failed: Manually add labels "Autodeploy Stage Review App" and "version-minor" to Esperanto PR

ERROR HANDLING

Critical Errors (stop immediately):

• HPP PR does not have 'qa-required' label
• No review version comment found
• yarn add fails
• Git operations fail
• PR creation fails
• GitHub MCP not available

Warnings (proceed with deployment):

• No file changes detected (version already deployed)
• Existing Esperanto PR found (update instead of create)
• Label addition fails (user can add manually)

Non-Critical Failures (log warning, continue):

• Label addition fails → User adds labels manually to Esperanto PR
• Comment addition fails → User can see deployment succeeded from Esperanto PR

All errors must:

• Log clear error message with recovery steps
• Exit immediately for critical errors (no retry)
• Provide actionable guidance to user
• For non-critical failures: Log warning and continue

### Step 5: Report Results

After sub-agent completes:

**On Success**:
- Display sub-agent's success message (includes deployment details table)
- Do NOT summarize or add commentary
- Success message includes next steps

**On Failure**:
- Display sub-agent's error message exactly
- Provide recovery guidance:
  - Missing 'qa-required' label → Add label to HPP PR
  - Missing version comment → Wait for review version to publish
  - yarn failure → Check Esperanto repo state and dependencies
  - GitHub MCP auth → Verify MCP server configuration
- **NEVER retry the sub-agent work yourself**

**Example Success Output**:

✓ Esperanto Review App Deployment Complete

Esperanto PR URL: https://github.com/krogertechnology/esperanto/pull/34671

Next Steps:

• Monitor Esperanto PR CI/CD checks for autodeploy to stage
• QA testing can begin once deployed
• Comment added to HPP PR with Esperanto PR link

---

## Verification

After skill execution, verify:

```bash
# 1. Branch exists in Esperanto (should match HPP PR branch name)
cd <path-to-esperanto-repo>
git branch --list "*<branch-name>*"

# 2. package.json updated
grep "@kroger/hosted-payment-page" package.json

# 3. PR created/updated
gh pr view <ESPERANTO-PR-NUMBER> --repo krogertechnology/esperanto --json title,labels,state

# 4. Comment added to HPP PR
gh pr view <HPP-PR-NUMBER> --repo krogertechnology/hosted-payment-page --comments | grep "Esperanto Review App Deployment"

Security

Safe Operations:

• Read-only access to HPP PR (fetch details and comments)
• Creates new branch or updates existing (non-destructive)
• No force-push or destructive git operations
• Version string validated before package update

Validation:

• Version format: \d+\.\d+\.\d+-[a-f0-9]+
• PR number: numeric only
• 'qa-required' label must exist

Authentication:

• GitHub auth via MCP server
• No API tokens in skill code
• No PII or sensitive data

Differences from upgrade-hpp Skill

Related Files