clickup-deploy-integration

ClickUp Deploy Integration

Overview

Deploy ClickUp-powered applications with secure token management. ClickUp API v2 is a standard REST API -- your app just needs CLICKUP_API_TOKEN available at runtime and outbound HTTPS to api.clickup.com.

Required Environment Variables

Variable	Purpose	Required
CLICKUP_API_TOKEN	Personal API token or OAuth access token	Yes
CLICKUP_TEAM_ID	Workspace ID for scoped operations	Recommended
CLICKUP_WEBHOOK_SECRET	For webhook signature validation	If using webhooks

Vercel Deployment

# Add secrets
vercel env add CLICKUP_API_TOKEN production
vercel env add CLICKUP_TEAM_ID production

# Deploy
vercel --prod

// api/clickup/tasks.ts (Vercel serverless function)
export async function GET(request: Request) {
  const listId = new URL(request.url).searchParams.get('list_id');
  if (!listId) return Response.json({ error: 'list_id required' }, { status: 400 });

  const response = await fetch(
    `https://api.clickup.com/api/v2/list/${listId}/task?archived=false`,
    { headers: { 'Authorization': process.env.CLICKUP_API_TOKEN! } }
  );

  if (!response.ok) {
    return Response.json({ error: 'ClickUp API error' }, { status: response.status });
  }

  const data = await response.json();
  return Response.json(data.tasks);
}

Fly.io Deployment

# Set secrets (encrypted at rest)
fly secrets set CLICKUP_API_TOKEN=pk_12345678_YOUR_TOKEN
fly secrets set CLICKUP_TEAM_ID=1234567

# Deploy
fly deploy

# fly.toml
app = "my-clickup-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

[[http_service.checks]]
  grace_period = "5s"
  interval = "30s"
  method = "GET"
  path = "/health"
  timeout = "5s"

Google Cloud Run

# Store token in Secret Manager
echo -n "pk_12345678_YOUR_TOKEN" | gcloud secrets create clickup-api-token --data-file=-

# Deploy with secret mounted as env var
gcloud run deploy clickup-service \
  --image gcr.io/$PROJECT_ID/clickup-service \
  --region us-central1 \
  --set-secrets=CLICKUP_API_TOKEN=clickup-api-token:latest \
  --set-env-vars=CLICKUP_TEAM_ID=1234567 \
  --allow-unauthenticated

Health Check Endpoint

// src/health.ts — verify ClickUp connectivity
export async function healthCheck() {
  const start = Date.now();

  try {
    const response = await fetch('https://api.clickup.com/api/v2/user', {
      headers: { 'Authorization': process.env.CLICKUP_API_TOKEN! },
      signal: AbortSignal.timeout(5000),
    });

    const remaining = response.headers.get('X-RateLimit-Remaining');

    return {
      status: response.ok ? 'healthy' : 'degraded',
      clickup: {
        connected: response.ok,
        httpStatus: response.status,
        latencyMs: Date.now() - start,
        rateLimitRemaining: remaining ? parseInt(remaining) : null,
      },
    };
  } catch (error) {
    return {
      status: 'unhealthy',
      clickup: {
        connected: false,
        error: error instanceof Error ? error.message : 'Unknown',
        latencyMs: Date.now() - start,
      },
    };
  }
}

Webhook Endpoint for Deployments

// api/webhooks/clickup.ts — receive ClickUp webhook events
export async function POST(request: Request) {
  const body = await request.json();

  // ClickUp webhook payloads include event type and history_items
  const { event, task_id, history_items } = body;

  // Process async (respond within 30s or ClickUp marks as failed)
  // Queue for processing if needed
  console.log(`ClickUp event: ${event} for task ${task_id}`);

  return Response.json({ received: true });
}

Error Handling

Issue	Cause	Solution
Secret not found in runtime	Missing env config	Verify with platform CLI
Cold start timeout	ClickUp API slow on first call	Set min instances = 1
Health check fails	Token rotated	Update secret, redeploy
Webhook endpoint 5xx	Slow processing	Respond 200 immediately, process async

Resources

• Vercel Environment Variables
• Fly.io Secrets
• Cloud Run Secret Manager

Next Steps

For webhook event handling, see clickup-webhooks-events.