alibabacloud-cadt-deploy-on-aliyun

name	alibabacloud-cadt-deploy-on-aliyun
description	Build and deploy applications to Alibaba Cloud ECS — Local build + script injection + InstallApplication async deployment. Triggers: build, deploy, CI/CD, compile & package, publish to Alibaba Cloud, diagnose, troubleshoot, root cause, 502, 503, service not started, deployment failed.
license	Apache-2.0

Alibaba Cloud Application Build & Deploy

Standalone deployment Skill: Build + Deploy pipeline orchestration. User directly provides ECS instance IDs, region, and application information — no project/environment hierarchy dependency.

Workflow

Path A: Build + Deploy (new deployment)

[step-1] Session init + collect deployment info  ->  [step-2] Compile, package & upload  ->  [step-3] Application deploy + failure recovery + result output

Path B: Diagnose + Fix + Redeploy (troubleshoot previous deployment)

[step-1] Session init + detect diagnose intent  ->  [step-3] §3.0-D Run diagnostics + classify root cause  ->  ⛔ ASK-USER "fix and re-deploy?" (mandatory STOP)  ->  [step-2] Build fix (config/scripts only, NOT new source code)  ->  [step-3] G4 checklist + InstallApplication

Path B scope: "Build" in Path B means applying the diagnosed fix to existing deployment configuration (e.g., application.yml port, JVM flags, start/stop scripts, env vars) and re-packaging — NOT writing new application source code from scratch. The application already exists on the ECS instance.

Path B re-deploy mandate: After the user confirms [1] "fix and re-deploy", the full pipeline (step-2 build → G4 checklist → InstallApplication → wait_ready) is always required — even when the diagnosed fix is infrastructure-level (e.g., security group rules, DNS, firewall). The ASK-USER says "re-deploy", which means InstallApplication. Applying infra fixes manually and then testing with ad-hoc curl is NOT a substitute for the deployment pipeline.

Step	Phase	File
[step-1]	Session init + collect deployment info	CLI Bootstrap + PATH validation + cadt-deploy-on-aliyun -doctor + ASK-USER collect regionId/instanceIds/appName + intent detection
[step-2]	Build	Local build + script injection + repackaging (output artifact file)
[step-3]	Deploy + Output	G4 install checklist (HITL, mandatory) -> InstallApplication (async: -run + -poll) -> wait_ready -> V18 post-deploy verification -> root cause analysis -> result output

Intent detection (in [step-1]): If the user's request mentions "diagnose", "troubleshoot", "root cause", "502", "service not started", "deployment failed", or similar troubleshooting keywords — route to Path B. Otherwise route to Path A. See [step-1] §6 for the decision logic.

⛔ Pre-Deploy Hard Gates (MANDATORY — do NOT call InstallApplication without these)

Before calling InstallApplication, you MUST complete ALL of the following gates. Each gate is independently verifiable from the execution transcript. Skipping any gate is a critical violation.

#	Gate	When	Evidence Required in Transcript
G0	ASK-USER for regionId + instanceIds when not in initial request	[step-1] before §5.4	Transcript MUST contain an explicit ASK-USER question for each missing field AND the user's response. Auto-discovery from CLI config, API enumeration, or env vars is a critical violation (see [step-1] §5.1–5.2).
G0a	cadt-deploy-on-aliyun -doctor run and passed	[step-1] §5 before §5 (Collect Deployment Info)	Transcript MUST contain cadt-deploy-on-aliyun -doctor invocation with all_ok: true result. doctor.json MUST be persisted. Skipping entirely is a critical violation (see [step-1] §5).
G1	COPYFILE_DISABLE=1 on ALL tar -czf commands	[step-2] packaging	Every tar command in transcript MUST have COPYFILE_DISABLE=1 prefix (required on ALL platforms — no-op on Linux, prevents AppleDouble on macOS)
G2	G4 Install Checklist presented + user confirmed [1]	[step-3] before InstallApplication	decisions.json with userResponse: "1" + userResponseAt timestamp. Agent text output alone is NOT sufficient.
G3	wait_ready loop executed after -poll SUCCESS	[step-3] after InstallApplication	Transcript MUST contain [wait_ready] T0: and [wait_ready] probe: markers. Ad-hoc curl or ps aux calls are NOT acceptable substitutes.
G4	ECS instance info queried via skill CLI only	[step-1] §5.4	Transcript MUST contain cadt-deploy-on-aliyun -run EcsGetDesc or EcsGetDescList. Direct aliyun ecs describe-instances calls are a critical violation — no exceptions, even when CLI bootstrap failed (fix it first).

Gate Details

G0 — ASK-USER for regionId + instanceIds (mandatory when not in initial request)

# CORRECT — user explicitly provided region and instance in their request
User: "Deploy to cn-beijing, instance i-bp1xxx"

# CORRECT — agent asks user when info is missing
Agent: "请提供部署目标的地域 (regionId)，例如 cn-hangzhou, cn-beijing"
User: "cn-hangzhou"
Agent: "请提供目标 ECS 实例 ID (instanceId)"
User: "i-bp1ai3ai0rpvx965zpw0"

# WRONG — agent auto-discovers region from CLI config (critical violation)
Agent runs: aliyun configure list → reads "cn-hangzhou" → proceeds without asking

# WRONG — agent auto-selects instance from API enumeration (critical violation)
Agent runs: aliyun ecs describe-instances → finds "order-api-ecs" → selects it without asking

G0a — -doctor check (mandatory before collecting deployment info)

# CORRECT — doctor run and evidence persisted
DOCTOR_RESULT=$(cadt-deploy-on-aliyun -doctor)
echo "$DOCTOR_RESULT" | jq .
# → all_ok: true, then persist to doctor.json

# WRONG — skipping doctor entirely (critical violation)
Agent reads SKILL.md → asks user for regionId → proceeds to EcsGetDesc without ever running -doctor

# WRONG — CLI bootstrap failed, agent abandons CLI and skips doctor (critical violation)
Agent runs: cadt-deploy-on-aliyun.sh -version → fails → uses raw aliyun CLI → never runs -doctor

If CLI bootstrap fails, you MUST fix the bootstrap first, then run -doctor. Abandoning the skill CLI and falling back to raw aliyun commands cascades into G0a and G4 violations.

G1 — COPYFILE_DISABLE=1 (all tar commands, all platforms)

# CORRECT — always use this prefix
COPYFILE_DISABLE=1 tar -czf "$ARTIFACT" -C "$STAGE_DIR" .

# WRONG — missing prefix (critical violation)
tar -czf "$ARTIFACT" -C "$STAGE_DIR" .
tar czf /tmp/app.tar.gz app scripts/

G2 — G4 Install Checklist (HITL gate — MUST present and STOP)

Before deployment, please confirm the install checklist:
  Application: {appName}
  Target instance(s): {instanceIds}
  Region: {regionId}
  Start command: {start.sh content}
  Stop command: {stop.sh content}
  Artifact: {ARTIFACT_FILE}

  [1] Checklist OK, proceed with deployment
  [2] I have additions / modifications
  [3] Cancel deployment

After presenting this checklist, you MUST STOP. No additional tool calls permitted. Wait for user response.

Deferred-modification rule: If the user responds [1] but the initial task prompt specified custom start/stop commands that were deferred (per §2.3 pre-baking prohibition), you MUST apply those commands, repackage, and re-present this checklist with the modified scripts before proceeding to InstallApplication. The user MUST see and confirm the actual commands that will run.

G3 — wait_ready loop (60s hard wait + 5s-interval probes)

# T0~T60: hard wait
echo "$(date '+%H:%M:%S') [wait_ready] T0: 60s hard wait"
sleep 60
# T60~T300: probe every 5s
# ... (full script in step-3 §3.2)

You MUST execute the FULL loop script from step-3 §3.2 using EcsRunCommandSync (probes localhost from inside the ECS). Ad-hoc single curl or ps aux commands are NOT acceptable. Do NOT substitute with a direct curl to the ECS public IP — security groups typically block inbound application ports, causing false timeouts even when the service is healthy internally.

G4 — Skill CLI required for ECS instance queries (no exceptions)

# CORRECT — use skill CLI
cadt-deploy-on-aliyun -run EcsGetDesc '{"regionId":"cn-hangzhou","instanceId":"i-bp1xxx"}'

# WRONG — direct ECS API bypass (critical violation, ALL forms forbidden)
aliyun ecs describe-instances --region-id cn-hangzhou
aliyun ecs describe-instances --region-id cn-hangzhou --instance-ids '["i-bp1xxx"]'
aliyun ecs describe-instance-attribute --instance-id i-bp1xxx

All ECS instance information queries MUST go through cadt-deploy-on-aliyun -run EcsGetDesc (single) or EcsGetDescList (batch). The skill CLI ensures normalized responses, --user-agent propagation, and auditable operation logs. If the skill CLI is unavailable (e.g., bootstrap failed), you MUST fix it before querying ECS info — using raw aliyun ecs as a workaround is still a critical violation.

Context Budget Management

This workflow has 3 major context-consuming phases: [step-1] init, [step-2] build, [step-3] deploy. Long builds (Maven downloading dependencies, npm install, etc.) can consume a large portion of the context window, leaving insufficient room for step-3.

Rules:

1. After any build that takes more than 30 seconds, immediately proceed to step-3 without re-reading SKILL.md or step files. The build output is already in context — do not re-summarize it.

2. Do NOT re-read step-2-build.md or step-3-deploy.md after the build completes. These files are large and will consume critical context budget. Read them ONCE during step-1/step-2, then proceed from memory.

3. Minimum context reservation for step-3: Before starting step-2 build, estimate the build size. If the build will produce verbose output (Maven downloading hundreds of JARs, npm install with thousands of packages), use -q (quiet) flags to suppress progress output:

   mvn -DskipTests package -q          # Maven quiet mode
   npm install --silent && npm pack    # npm silent mode
   pip install build -q                # pip quiet mode
   

4. If context is running low after build: Skip re-verification of build artifacts (the build exit code is sufficient) and proceed directly to script injection + repackaging + G4 + InstallApplication.

Standalone Entry Point

The user directly provides the following information:

• regionId (required): ECS instance region, e.g. cn-hangzhou
• instanceIds (required): ECS instance IDs, e.g. i-bp1xxxxx
• appName (required): application name, e.g. my-app
• Build info (optional, if building from source): language, languageVersion, buildTool

All data is user-provided; no project/environment ID lookups needed.

⛔ No auto-discovery (critical): regionId and instanceIds MUST come from the user's explicit input. Do NOT auto-discover them from CLI configuration (aliyun configure list), API enumeration (aliyun ecs describe-instances), environment variables, or any other automated source. If not provided by the user, you MUST ASK-USER. See [step-1] §5.1–5.2 for details. Deploying to an auto-selected region or instance is a critical violation.

Dependencies

Tool	Purpose
cadt-deploy-on-aliyun CLI (built-in)	Operation dispatch (cadt-deploy-on-aliyun -run <Op>)
aliyun CLI	STS / OSS / ECS API
jq	JSON parsing
bash 4.0+	Script execution

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} below.

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag. Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-cadt-deploy-on-aliyun/{session-id}

Propagation paths (choose the right one per context)

Context	How to propagate	Who adds --user-agent
cadt-deploy-on-aliyun -run / -poll	export SKILL_SESSION_ID={session-id} once per shell	CLI auto-injects into all internal aliyun calls
Direct aliyun CLI calls	Append --user-agent ... inline on every command	You (the agent) must add it manually
Python/bash scripts	SKILL_SESSION_ID={session-id} python3 script.py	Script reads env var and adds --user-agent

Path A: cadt-deploy-on-aliyun CLI (recommended)

Export SKILL_SESSION_ID once at session init (see [step-1] §4). The CLI automatically propagates it to all internal aliyun subprocess calls — you do NOT need to add --user-agent to each -run / -poll invocation:

export SKILL_SESSION_ID={session-id}
cadt-deploy-on-aliyun -run InstallApplication '{"regionId":"cn-hangzhou",...}'

Alternatively, pass --user-agent directly on the CLI command line (the CLI extracts the session-id and sets it for the current invocation):

cadt-deploy-on-aliyun -run InstallApplication '{"regionId":"cn-hangzhou",...}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cadt-deploy-on-aliyun/{session-id}

Path B: Direct aliyun CLI calls

When calling aliyun directly (not through cadt-deploy-on-aliyun), you MUST append --user-agent on every command:

aliyun bpstudio get-token --api-version 2021-09-31 --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cadt-deploy-on-aliyun/{session-id}

Do not skip, alter the format, or omit --user-agent on any aliyun API command invocation.

Path C: Script execution

When running Python SDK scripts or bash scripts, inject the session-id via inline environment variable:

SKILL_SESSION_ID={session-id} python3 scripts/deploy.py

Scripts should read SKILL_SESSION_ID from the environment (default to empty string if absent).

CLI Quick Start

# cadt-deploy-on-aliyun CLI auto-creates venv and installs dependencies
./scripts/cli/cadt-deploy-on-aliyun.sh -version
./scripts/cli/cadt-deploy-on-aliyun.sh -l                    # List all available operations
./scripts/cli/cadt-deploy-on-aliyun.sh -d InstallApplication  # View operation schema

Available Operations

Operation	Category	Mode	Description
InstallApplication	deploy	async	Deploy to ECS (filePath auto-upload)
EcsGetDesc	ecs	sync	Query single ECS instance info (IP, status, OS)
EcsGetDescList	ecs	sync	Batch query multiple ECS instances info
EcsRunCommand	ecs	async	Run shell commands on ECS (Cloud Assistant)
EcsSendFile	ecs	sync	Send files to ECS (Cloud Assistant)
OssGeneratePresignedUrl	oss	sync	Generate presigned download URL for OSS object

Async operations (InstallApplication, EcsRunCommand) are two-step:

1. cadt-deploy-on-aliyun -run <Op> '{...}' → submits the task, returns invocationId
2. cadt-deploy-on-aliyun -poll <invocationId> → blocks until completion, returns final status

The -run command for async ops is non-blocking — it returns status: submitted immediately. You MUST invoke -poll as a separate CLI command to wait for the result. Skipping -poll and self-reporting success is a critical violation.