Academic ResearchIntermediate

Deploy Workflow Automation

Automate your deployment pipeline: build, test, lint, version bump, and deploy to any target. Includes pre-deploy checks, rollback handling, and post-deploy verification.

15 minutes

By communitySource

#deploy#ci-cd#automation#release#devops#pipeline

Deploying means running 6 commands in the right order, remembering to bump the version, hoping the tests pass, and crossing your fingers nothing breaks in production. One missed step and you're rolling back at midnight.

Who it's for: developers deploying manually and making mistakes, teams without CI/CD wanting structured releases, solo developers shipping to production, engineering leads standardizing deployment processes, anyone who's deployed on a Friday and regretted it

Example

"Set up a deploy workflow for our Node.js app" → Automated pipeline: pre-deploy checks (build, test, lint), version bump, deployment to target, post-deploy verification, and rollback procedure if anything fails — one command to ship safely

CLAUDE.md Template

New here? 3-minute setup guide → | Already set up? Copy the template below.

# Deploy Workflow Protocol

## Activation

When I say "/deploy", "deploy to [target]", or "release", activate this protocol.

## Deployment Configuration

```yaml
# Customize for your project
project_name: "my-project"
deploy_targets:
  production:
    command: "vercel --prod"
    url: "https://myapp.com"
    requires_approval: true
  staging:
    command: "vercel"
    url: "https://staging.myapp.com"
    requires_approval: false
  npm:
    command: "npm publish"
    requires_approval: true
version_file: "package.json"  # or Cargo.toml, pyproject.toml, etc.
```

## Deploy Pipeline

```
┌─────────────────────────────────────────────────────────┐
│                    PRE-DEPLOY PHASE                      │
├─────────────────────────────────────────────────────────┤
│  1. Check clean git status (no uncommitted changes)      │
│  2. Pull latest from main/master                         │
│  3. Run tests                                            │
│  4. Run linter                                           │
│  5. Run build                                            │
│  6. Check for security vulnerabilities                   │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │ All OK? │
                    └────┬────┘
                        / \
                      YES   NO
                       │     │
                       │     └─▶ STOP: Fix issues first
                       │
┌──────────────────────▼──────────────────────────────────┐
│                    VERSION PHASE                         │
├─────────────────────────────────────────────────────────┤
│  1. Determine version bump (patch/minor/major)          │
│  2. Update version in config files                      │
│  3. Update CHANGELOG.md                                  │
│  4. Commit version bump                                  │
│  5. Create git tag                                       │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                    DEPLOY PHASE                          │
├─────────────────────────────────────────────────────────┤
│  1. Push to remote (triggers CI/CD if configured)       │
│  2. Run deploy command                                   │
│  3. Wait for deployment to complete                      │
│  4. Run smoke tests on deployed URL                      │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │Success? │
                    └────┬────┘
                        / \
                      YES   NO
                       │     │
                       │     └─▶ Initiate rollback
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   POST-DEPLOY PHASE                      │
├─────────────────────────────────────────────────────────┤
│  1. Verify deployment URL is accessible                  │
│  2. Check health endpoint                                │
│  3. Update deployment log                                │
│  4. Notify (if configured)                               │
└─────────────────────────────────────────────────────────┘
```

## Pre-Deploy Checks

Run these checks before ANY deployment:

### 1. Clean Git Status
```bash
git status --porcelain
# Must be empty (no uncommitted changes)
```

### 2. Tests Pass
```bash
npm test  # or pytest, cargo test, go test
# Exit code must be 0
```

### 3. Lint Passes
```bash
npm run lint  # or equivalent
# Exit code must be 0
```

### 4. Build Succeeds
```bash
npm run build  # or equivalent
# Exit code must be 0
```

### 5. Security Check (optional but recommended)
```bash
npm audit  # or cargo audit, safety check
# No high/critical vulnerabilities
```

## Pre-Deploy Report

```
## Pre-Deploy Checklist

**Target**: production
**Branch**: main

| Check | Status | Details |
|-------|--------|---------|
| Git clean | ✓ | No uncommitted changes |
| Tests | ✓ | 47/47 passing |
| Lint | ✓ | 0 errors, 2 warnings |
| Build | ✓ | Completed in 12.3s |
| Security | ✓ | No vulnerabilities |

**All checks passed. Ready to deploy.**
```

## Version Bump Rules

### Semantic Versioning (semver)
- **patch** (1.0.0 → 1.0.1): Bug fixes, no new features
- **minor** (1.0.0 → 1.1.0): New features, backwards compatible
- **major** (1.0.0 → 2.0.0): Breaking changes

### Auto-Detect from Commits
```
feat: → minor bump
fix: → patch bump
BREAKING CHANGE: → major bump
chore/docs/style: → no version bump (unless forced)
```

### Version Update Locations
Update version in:
- package.json (Node.js)
- Cargo.toml (Rust)
- pyproject.toml (Python)
- VERSION file
- App constants (if hardcoded)

## Deploy Commands by Target

### Vercel
```bash
vercel --prod  # production
vercel  # preview/staging
```

### Netlify
```bash
netlify deploy --prod
netlify deploy  # draft
```

### npm Registry
```bash
npm publish
npm publish --tag beta  # pre-release
```

### Docker
```bash
docker build -t myapp:$VERSION .
docker push myapp:$VERSION
```

### Custom Server
```bash
ssh server "cd /app && git pull && npm install && pm2 restart all"
```

## Post-Deploy Verification

### Health Check
```bash
curl -f https://myapp.com/health
# Must return 200 OK
```

### Smoke Test
```bash
# Verify critical paths work
curl -f https://myapp.com/
curl -f https://myapp.com/api/status
```

### Version Check
```bash
curl https://myapp.com/api/version
# Must match deployed version
```

## Rollback Protocol

If deployment fails or verification fails:

1. **Identify last good version** from git tags
2. **Revert**: `git revert HEAD` or redeploy previous tag
3. **Redeploy** the last known good version
4. **Verify** rollback succeeded
5. **Document** what went wrong

```
## Rollback Executed

**Reason**: Health check failed after deploy
**Rolled back from**: v1.2.3
**Rolled back to**: v1.2.2
**Status**: ✓ Rollback successful, site operational
```

## Deploy Report Format

```
## Deployment Report

**Project**: my-project
**Target**: production
**Version**: 1.2.3 → 1.2.4

### Pre-Deploy
- Tests: ✓ 47 passing
- Build: ✓ 12.3s
- Lint: ✓ Clean

### Deploy
- Command: vercel --prod
- Duration: 45s
- URL: https://myapp.com

### Verification
- Health: ✓ 200 OK
- Response time: 234ms
- Version endpoint: ✓ Returns 1.2.4

**Status**: ✓ DEPLOYED SUCCESSFULLY

**Changelog**:
- Fixed authentication bug (#123)
- Added dark mode toggle (#124)
```

## Invoking Deploy

```
/deploy              # Deploy to default target
/deploy production   # Deploy to specific target
/deploy staging      # Deploy to staging
release patch        # Bump patch version and deploy
release minor        # Bump minor version and deploy
```

README.md

What This Does

This playbook creates a structured deployment workflow that:

Runs pre-deploy checks (build, test, lint)
Bumps version numbers
Executes deployment commands
Verifies the deployment succeeded
Handles rollback if needed

Why automate deploys: Manual deploys are error-prone. Miss a step and you ship bugs. This workflow ensures every deploy follows the same reliable process.

Prerequisites

Claude Code installed
A deployable project (web app, package, static site, etc.)
Deployment target configured (Vercel, Netlify, npm, Docker, etc.)

Deploy Pipeline

┌─────────────────────────────────────────────────────────┐
│                    PRE-DEPLOY PHASE                      │
├─────────────────────────────────────────────────────────┤
│  1. Check clean git status (no uncommitted changes)      │
│  2. Pull latest from main/master                         │
│  3. Run tests                                            │
│  4. Run linter                                           │
│  5. Run build                                            │
│  6. Check for security vulnerabilities                   │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │ All OK? │
                    └────┬────┘
                        / \
                      YES   NO
                       │     │
                       │     └─▶ STOP: Fix issues first
                       │
┌──────────────────────▼──────────────────────────────────┐
│                    VERSION PHASE                         │
├─────────────────────────────────────────────────────────┤
│  1. Determine version bump (patch/minor/major)          │
│  2. Update version in config files                      │
│  3. Update CHANGELOG.md                                  │
│  4. Commit version bump                                  │
│  5. Create git tag                                       │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                    DEPLOY PHASE                          │
├─────────────────────────────────────────────────────────┤
│  1. Push to remote (triggers CI/CD if configured)       │
│  2. Run deploy command                                   │
│  3. Wait for deployment to complete                      │
│  4. Run smoke tests on deployed URL                      │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │Success? │
                    └────┬────┘
                        / \
                      YES   NO
                       │     │
                       │     └─▶ Initiate rollback
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   POST-DEPLOY PHASE                      │
├─────────────────────────────────────────────────────────┤
│  1. Verify deployment URL is accessible                  │
│  2. Check health endpoint                                │
│  3. Update deployment log                                │
│  4. Notify (if configured)                               │
└─────────────────────────────────────────────────────────┘

Pre-Deploy Checks

Run these checks before ANY deployment:

1. Clean Git Status

git status --porcelain
# Must be empty (no uncommitted changes)

2. Tests Pass

npm test  # or pytest, cargo test, go test
# Exit code must be 0

3. Lint Passes

npm run lint  # or equivalent
# Exit code must be 0

4. Build Succeeds

npm run build  # or equivalent
# Exit code must be 0

5. Security Check (optional but recommended)

npm audit  # or cargo audit, safety check
# No high/critical vulnerabilities

Pre-Deploy Report

## Pre-Deploy Checklist

**Target**: production
**Branch**: main

| Check | Status | Details |
|-------|--------|---------|
| Git clean | ✓ | No uncommitted changes |
| Tests | ✓ | 47/47 passing |
| Lint | ✓ | 0 errors, 2 warnings |
| Build | ✓ | Completed in 12.3s |
| Security | ✓ | No vulnerabilities |

**All checks passed. Ready to deploy.**

Version Bump Rules

Semantic Versioning (semver)

patch (1.0.0 → 1.0.1): Bug fixes, no new features
minor (1.0.0 → 1.1.0): New features, backwards compatible
major (1.0.0 → 2.0.0): Breaking changes

Auto-Detect from Commits

feat: → minor bump
fix: → patch bump
BREAKING CHANGE: → major bump
chore/docs/style: → no version bump (unless forced)

Version Update Locations

Update version in:

package.json (Node.js)
Cargo.toml (Rust)
pyproject.toml (Python)
VERSION file
App constants (if hardcoded)

Deploy Commands by Target

Vercel

vercel --prod  # production
vercel  # preview/staging

Netlify

netlify deploy --prod
netlify deploy  # draft

npm Registry

npm publish
npm publish --tag beta  # pre-release

Docker

docker build -t myapp:$VERSION .
docker push myapp:$VERSION

Custom Server

ssh server "cd /app && git pull && npm install && pm2 restart all"

Post-Deploy Verification

Health Check

curl -f https://myapp.com/health
# Must return 200 OK

Smoke Test

# Verify critical paths work
curl -f https://myapp.com/
curl -f https://myapp.com/api/status

Version Check

curl https://myapp.com/api/version
# Must match deployed version

Rollback Protocol

If deployment fails or verification fails:

Identify last good version from git tags
Revert: git revert HEAD or redeploy previous tag
Redeploy the last known good version
Verify rollback succeeded
Document what went wrong

## Rollback Executed

**Reason**: Health check failed after deploy
**Rolled back from**: v1.2.3
**Rolled back to**: v1.2.2
**Status**: ✓ Rollback successful, site operational

Deploy Report Format

## Deployment Report

**Project**: my-project
**Target**: production
**Version**: 1.2.3 → 1.2.4

### Pre-Deploy
- Tests: ✓ 47 passing
- Build: ✓ 12.3s
- Lint: ✓ Clean

### Deploy
- Command: vercel --prod
- Duration: 45s
- URL: https://myapp.com

### Verification
- Health: ✓ 200 OK
- Response time: 234ms
- Version endpoint: ✓ Returns 1.2.4

**Status**: ✓ DEPLOYED SUCCESSFULLY

**Changelog**:
- Fixed authentication bug (#123)
- Added dark mode toggle (#124)

Invoking Deploy

/deploy              # Deploy to default target
/deploy production   # Deploy to specific target
/deploy staging      # Deploy to staging
release patch        # Bump patch version and deploy
release minor        # Bump minor version and deploy


## Step-by-Step Setup

### Step 1: Add to CLAUDE.md

Add the deploy protocol to your project's CLAUDE.md file.

### Step 2: Configure your deploy targets

Update the `deploy_targets` section with your actual deployment commands:
- Vercel: `vercel --prod`
- Netlify: `netlify deploy --prod`
- npm: `npm publish`
- Custom: your deploy script

### Step 3: Test with staging first

/deploy staging


Verify the full pipeline works before attempting production.

### Step 4: Deploy to production

/deploy production


Claude will run all checks, bump version, deploy, and verify.

## Example Usage

**User:**
> "/deploy production"

**Claude:**
> ## Pre-Deploy Checklist
>
> **Target**: production
> **Branch**: main
>
> | Check | Status |
> |-------|--------|
> | Git clean | ✓ |
> | Tests | ✓ 47/47 passing |
> | Lint | ✓ Clean |
> | Build | ✓ 12.3s |
>
> **All checks passed.**
>
> ---
>
> ## Version Bump
>
> Analyzing commits since v1.2.3...
> - feat: Add dark mode → minor bump
>
> Bumping version: 1.2.3 → 1.3.0
>
> Updated: package.json
> Created commit: "chore: bump version to 1.3.0"
> Created tag: v1.3.0
>
> ---
>
> ## Deploying
>
> Running: vercel --prod
> Deployment URL: https://myapp.vercel.app
>
> Waiting for propagation...
>
> ## Verification
>
> - Health check: ✓ 200 OK
> - Version endpoint: ✓ Returns 1.3.0
> - Response time: 189ms
>
> ---
>
> ## ✓ Deployment Successful
>
> **Version**: 1.3.0
> **URL**: https://myapp.com
> **Time**: 2 minutes 34 seconds

## Tips

- **Always deploy to staging first**: Catch issues before they hit production.
- **Use version tags**: Makes rollback trivial — just redeploy the tag.
- **Automate notifications**: Add Slack/Discord webhook to post-deploy phase.
- **Keep CHANGELOG updated**: The version phase can auto-generate from commits.

## Troubleshooting

**Problem**: Deploy command fails but site seems up

**Solution**: Check if deployment is async. Some platforms (Vercel, Netlify) return before fully propagated.

**Problem**: Health check fails immediately after deploy

**Solution**: Add a delay: "Wait 30 seconds after deploy before verification."

**Problem**: Version bump conflicts with CI

**Solution**: Configure CI to skip builds on version bump commits: `[skip ci]` in message.