run-deploy: GitHub Actions Deployment Trigger

The "hand" of the harness. Validates deployment readiness, fires the configured GitHub Actions workflow via workflow_dispatch, monitors completion, and verifies the service is healthy afterward.

• NEVER auto-invoked without passing the full pre-deploy checklist
• Requires explicit conditions — does not deploy blindly
• Writes results to agent/state/deploy.json

Safety Rules

1. HALT file — Mandatory first check. If present, print reason and stop.
2. Pre-deploy checklist — All six conditions must pass before triggering.
3. gh required — Cannot deploy without GitHub CLI. If unavailable, error and exit.
4. No blind deploys — config.deploy_workflow must be explicitly configured.

Step 0: Safety

0-A: HALT Check

if file exists at config.safety.halt_file:
  Print "[HALT] run-deploy stopped. Reason: {file_content}"
  EXIT immediately.

0-B: Config Validation

if config.deploy_workflow is missing, null, or empty:
  Print "No deploy workflow configured. Skipping."
  EXIT cleanly (not an error).

Step 1: Pre-Deploy Checklist

All six conditions must pass. On first failure, print the reason and skip deployment.

On any failure:

Pre-deploy checklist FAILED: {reason}
Deployment skipped.

State files missing (health, tests) count as unknown — treat as failure for that check. Print which specific check failed so the user can act on it.

Step 2: Trigger Deployment

Verify gh is available and authenticated:

gh --version
gh auth status

If not found: print ERROR: gh (GitHub CLI) is required for deployment. Install from https://cli.github.com/ and exit non-zero. If not authenticated: print ERROR: gh is not authenticated. Run: gh auth login and exit non-zero.

Determine the current branch:

git rev-parse --abbrev-ref HEAD

Trigger the workflow. If config.deploy_workflow_inputs is set (object of key-value pairs), pass each entry as -f key=value:

# Without inputs:
gh workflow run {config.deploy_workflow} --ref {branch}

# With inputs (e.g. {"environment":"staging","tag":"v1.2.3"}):
gh workflow run {config.deploy_workflow} --ref {branch} -f environment=staging -f tag=v1.2.3

Wait up to 15 seconds for the run to register, then retrieve the run ID:

gh run list --workflow={config.deploy_workflow} --limit=1 --json databaseId,url --jq '.[0]'

Print:

Deployment triggered: {config.deploy_workflow} on {branch}
Workflow run: {run_url}

Step 3: Monitor

Watch the run until completion. Timeout is read from config.deploy_monitor_timeout_seconds (default 600 — 10 minutes):

gh run watch {run_id} --exit-status

• Exit 0 → status: "success"
• Non-zero exit → status: "failed"
• Timeout (> configured seconds): kill watch, record status: "unknown", print:

Deployment monitor timed out after {timeout}s. Check {run_url} manually.

Re-check the HALT file after the wait completes. If it appeared during the long monitor window, record status: "halted" and skip post-deploy steps.

Step 4: Post-Deploy Health Check

Skip this step if config.health_endpoints is missing or empty — note the skip.

If endpoints are configured:

1. Wait config.deploy_health_wait_seconds (default 30) for the service to stabilize.
2. Run health checks using the same logic as scan-health (Step 2 of that skill).
3. If any endpoint fails, retry once after another deploy_health_wait_seconds wait

(services with rolling deploys may need extra time).

1. Evaluate final results:

• All endpoints 200 → health_check: "passed" — print Deployment verified healthy.
• Any endpoint non-200 or critical alert after retry → health_check: "failed" — print:

ALERT: Post-deploy health check failed after retry. Consider rollback.

Step 5: State Update + Report

Write to agent/state/deploy.json:

{
  "schema_version": "1.1.0",
  "last_deploy": "<ISO 8601>",
  "deploy_count": N,
  "status": "success|failed|unknown|halted",
  "workflow": "{config.deploy_workflow}",
  "branch": "{branch}",
  "commit_sha": "{HEAD short SHA at trigger time}",
  "run_id": "{run_id}",
  "run_url": "{run_url}",
  "health_check": "passed|failed|skipped",
  "health_retry_count": 0,
  "duration_seconds": N,
  "error_message": null
}

deploy_count: increment from previous value in the file (default 0 if file absent). commit_sha: captured via git rev-parse --short HEAD before triggering. duration_seconds: wall-clock time from trigger to final state write. error_message: null on success; short description on failure/unknown.

Print deployment summary:

run-deploy — <ISO timestamp>
Workflow : {config.deploy_workflow}
Branch   : {branch}
Commit   : {commit_sha}
Run ID   : {run_id}
Status   : success | failed | unknown | halted
Health   : passed | failed | skipped
Duration : {duration_seconds}s
Run URL  : {run_url}

If status == "failed": print Workflow failed. Investigate at {run_url} before retrying. If status == "halted": print HALT file appeared during deployment. Monitoring stopped. If health_check == "failed": print Post-deploy health check failed after retry. Manual rollback may be needed.

Graceful Degradation