Agent Skills: ClickUp Production Checklist

ClickUp Production Checklist

Overview

Complete checklist for deploying ClickUp API v2 integrations to production.

Pre-Launch Checklist

Authentication & Secrets

• [ ] Production API token stored in secrets manager (not env files)
• [ ] Token uses a service account, not a personal user account
• [ ] .env files in .gitignore; pre-commit hook catches pk_* patterns
• [ ] Token rotation procedure documented and tested
• [ ] OAuth client secret server-side only (never in client bundle)

Error Handling

• [ ] All API calls handle 401 (re-auth), 429 (backoff), 500 (retry)
• [ ] Exponential backoff with jitter on rate limits
• [ ] ClickUp-specific error codes parsed (ECODE field in responses)
• [ ] Circuit breaker pattern prevents cascade failures
• [ ] Graceful degradation when ClickUp API is down

Rate Limits

• [ ] Know your plan's limit (100/1K/10K req/min)
• [ ] Rate limit headers monitored (X-RateLimit-Remaining)
• [ ] Request queuing prevents burst overruns
• [ ] Caching reduces unnecessary API calls
• [ ] Webhooks replace polling where possible

Monitoring

• [ ] Health check endpoint verifies ClickUp connectivity
• [ ] API latency tracked per endpoint
• [ ] Error rate alerting (>5% triggers P2)
• [ ] Rate limit remaining alerting (<10% triggers warning)
• [ ] Structured logging with request/response metadata

Webhooks (if applicable)

• [ ] Endpoint uses HTTPS
• [ ] Responds with 200 within 30 seconds
• [ ] Idempotent processing (tracks history_items[].id)
• [ ] Async processing after immediate 200 response
• [ ] Handles ClickUp auto-disable (re-register if needed)

Production Health Verification

#!/bin/bash
# run-prod-checks.sh

echo "=== ClickUp Production Checks ==="

# 1. Auth works
echo -n "Auth: "
STATUS=$(curl -sf -o /dev/null -w "%{http_code}" \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN")
[ "$STATUS" = "200" ] && echo "PASS" || echo "FAIL ($STATUS)"

# 2. Rate limit headroom
echo -n "Rate limit: "
REMAINING=$(curl -sD - -o /dev/null \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN" 2>&1 | \
  grep -i "X-RateLimit-Remaining" | awk '{print $2}' | tr -d '\r')
echo "${REMAINING} remaining"

# 3. API latency
echo -n "Latency: "
LATENCY=$(curl -sf -o /dev/null -w "%{time_total}" \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN")
echo "${LATENCY}s"
[ "$(echo "$LATENCY > 2" | bc -l)" = "1" ] && echo "  WARNING: latency > 2s"

# 4. Workspace accessible
echo -n "Workspaces: "
TEAMS=$(curl -sf https://api.clickup.com/api/v2/team \
  -H "Authorization: $CLICKUP_API_TOKEN" | \
  python3 -c "import sys,json; print(len(json.load(sys.stdin)['teams']))" 2>/dev/null)
echo "${TEAMS} accessible"

# 5. ClickUp platform status
echo -n "Platform: "
curl -sf https://status.clickup.com/api/v2/summary.json | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['status']['description'])" 2>/dev/null || echo "Unknown"

echo "=== Checks Complete ==="

Rollback Procedure

# 1. If ClickUp token is compromised
# - Regenerate token in ClickUp Settings > Apps
# - Update secret in deployment platform
# - Redeploy

# 2. If integration is causing issues
# - Feature flag: disable ClickUp integration
# - Or: set CLICKUP_ENABLED=false and redeploy

# 3. If version upgrade broke things
# - Revert deployment to previous version
# - Pin API calls to specific behavior (no v3 endpoints)

Error Handling

| Alert | Condition | Severity | |-------|-----------|----------| | API unreachable | 0 successful requests in 5min | P1 | | Auth failures | Any 401 response | P1 | | Rate limited | X-RateLimit-Remaining = 0 | P2 | | High latency | P95 > 3 seconds | P2 | | Webhook failures | 3+ consecutive 5xx | P3 |

Resources

• ClickUp Status Page
• ClickUp Rate Limits

Next Steps

For version upgrades, see clickup-upgrade-migration.