---
name: api-deploy-workflow-ad54dff9419c
description: >
  Guide deployments of API services through staging and production environments with
  health checks, rollback procedures, and verification steps. Triggers when user says
  "deploy API", "push to staging", "release to production", "rollback deployment",
  or discusses CI/CD pipelines for backend services.
  指导 API 服务的部署流程，涵盖 staging/production 环境、健康检查、回滚和验证。
allowed-tools: Read Bash Grep Glob Write
---

# API Deploy Workflow

Automate and standardize API service deployments across staging and production environments with built-in safety checks.

## When to Use

- User wants to deploy an API service to staging or production
- User needs to roll back a failed deployment
- User is setting up a deployment pipeline for a backend service
- User asks about blue-green or canary deployment strategies
- User mentions "deploy", "release", "rollback", "staging", "production" in the context of backend services

## When NOT to Use

- Frontend/static site deployments (different tooling: Vercel, Netlify, etc.)
- Database migrations without accompanying code changes (use a dedicated migration skill)
- Infrastructure provisioning (Terraform, Pulumi — different scope)
- Deploying ML models (different pipeline: model registry, A/B testing)

## Prerequisites

- Docker installed and configured
- `kubectl` or target platform CLI authenticated
- Container registry access (ECR, GCR, Docker Hub)
- Environment config files in place (see `references/environment-config.md`)

## Step-by-Step Workflow

### Phase 1: Pre-Deploy Validation

1. **Run tests**: Ensure all unit and integration tests pass
   ```bash
   npm test        # or pytest, go test, etc.
   ```
2. **Build container image**: Tag with git SHA for traceability
   ```bash
   docker build -t $REGISTRY/$SERVICE:$(git rev-parse --short HEAD) .
   ```
3. **Push image to registry**:
   ```bash
   docker push $REGISTRY/$SERVICE:$(git rev-parse --short HEAD)
   ```

### Phase 2: Deploy to Staging

4. **Update staging manifest** with new image tag
5. **Apply to staging cluster**:
   ```bash
   kubectl apply -f k8s/staging/ --namespace=staging
   ```
6. **Wait for rollout**:
   ```bash
   kubectl rollout status deployment/$SERVICE --namespace=staging --timeout=300s
   ```
7. **Run health check** against staging endpoint:
   ```bash
   python3 ${CLAUDE_SKILL_DIR}/scripts/health_check.py https://staging-api.example.com/health
   ```

### Phase 3: Staging Verification

8. **Smoke test**: Hit critical endpoints and verify responses
9. **Check logs** for errors in the first 5 minutes
10. **Compare metrics** (latency, error rate) against baseline

### Phase 4: Deploy to Production

11. **Get approval**: Confirm with the user before proceeding
12. **Apply to production cluster**:
    ```bash
    kubectl apply -f k8s/production/ --namespace=production
    ```
13. **Monitor rollout**:
    ```bash
    kubectl rollout status deployment/$SERVICE --namespace=production --timeout=300s
    ```
14. **Run production health check**:
    ```bash
    python3 ${CLAUDE_SKILL_DIR}/scripts/health_check.py https://api.example.com/health
    ```

### Phase 5: Post-Deploy

15. **Tag the release** in git:
    ```bash
    git tag -a v$VERSION -m "Release v$VERSION"
    git push origin v$VERSION
    ```
16. **Notify team** with deployment summary

## Input/Output Spec

- **Input**: Service name, target environment (staging/production), git ref or image tag
- **Output**: Deployed service with verified health, git tag, deployment summary

## Commands

| Command | Description |
|---------|-------------|
| `/api-deploy-workflow:deploy-staging` | Deploy to staging with health checks |
| `/api-deploy-workflow:deploy-prod` | Deploy to production (requires staging success) |
| `/api-deploy-workflow:rollback` | Roll back to previous stable version |

See `commands/` directory for detailed command definitions.

## Scripts

- `scripts/health_check.py` — HTTP health check with retry logic and timeout handling. See script for usage.

## Verification

After each deployment:
1. Health endpoint returns 200 with `{"status": "healthy"}`
2. No increase in error rate (5xx) over 5 minutes
3. p99 latency stays within 2x of pre-deploy baseline
4. All critical API endpoints respond correctly

## Edge Cases & Error Handling

| Scenario | Action |
|----------|--------|
| Health check fails after deploy | Automatic rollback via `/api-deploy-workflow:rollback` |
| Rollout timeout (>300s) | Abort and rollback, check pod events for crash loops |
| Registry push fails | Retry with exponential backoff; check auth tokens |
| Staging passes but production fails | Investigate env-specific config differences (see `references/environment-config.md`) |
| Partial rollout (some pods updated) | Use `kubectl rollout undo` to restore consistency |

## Examples

### Example 1: Standard Staging Deploy

**Input**: "Deploy the user-service to staging from the feature/auth-v2 branch"

**Execution**:
1. Checks out `feature/auth-v2`, runs tests — all pass
2. Builds `registry.example.com/user-service:a3f7b2c`
3. Pushes to registry
4. Updates staging manifest, applies to cluster
5. Health check passes: `{"status": "healthy", "version": "a3f7b2c"}`

**Output**: "user-service deployed to staging. Health check passed. Version: a3f7b2c. Ready for production deploy when you give the go-ahead."

### Example 2: Production Rollback

**Input**: "The API is returning 503s after the last deploy — roll back now"

**Execution**:
1. Identifies current deployment: `v2.4.1` (image tag `b8e2d1f`)
2. Finds previous stable version: `v2.4.0` (image tag `9c1a4e3`)
3. Runs `kubectl rollout undo deployment/user-service --namespace=production`
4. Monitors rollout, runs health check
5. Confirms error rate drops to baseline

**Output**: "Rolled back user-service from v2.4.1 to v2.4.0. Health check passed. Error rate normalized. Recommend investigating the v2.4.1 changes before re-deploying."

## References

- `references/environment-config.md` — Environment-specific configuration patterns and secrets management


---
Source attribution: skillforgeai-dev
Original project: https://github.com/skillforgeai-dev/content-to-skill/blob/a5dd693952b6e74a48b3d5af37296007c63577c9/examples/api-deploy-workflow/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 content-to-skill contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: skillforgeai-dev
Original project: https://github.com/skillforgeai-dev/content-to-skill/blob/a5dd693952b6e74a48b3d5af37296007c63577c9/examples/api-deploy-workflow/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, DevOps / SRE, Product Manager
Specialties: API, DevOps
Tools: Docker, Kubernetes
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: fa0ef55811e30d6acee6050ceda9bc8e7fe2a1b7be46c5653b572df5a582d46f