GitHub-ClickUp Integration: Troubleshooting

Debug common integration issues and resolve problems quickly

Audience: All users, support team Purpose: Fix integration issues fast with step-by-step solutions

Prerequisites: - Integration setup completed (see Quick Start Guide) - Access to GitHub Actions logs - Access to ClickUp automation logs

---

Quick Diagnostic Checklist

Before diving into specific issues, run through this checklist:

• [ ] Branch name includes ClickUp task ID (format: feature/CU-123abc-description)
• [ ] PR targets develop branch (or your configured branch)
• [ ] GitHub Actions workflows exist in .github/workflows/
• [ ] CLICKUP_TASKS_UPDATE_TOKEN secret is set in GitHub
• [ ] ClickUp task exists and is accessible
• [ ] GitHub Actions workflow ran (check Actions tab)
• [ ] No GitHub Actions errors in logs

---

Issue 1: Branch Name Missing Task ID

Symptoms

• GitHub Action runs but skips ClickUp update
• Log shows: "No ClickUp task ID found in branch name"
• Task status doesn't change when PR is created

Root Causes

1. Branch name doesn't contain CU- prefix
2. Task ID format is incorrect
3. Branch renamed after PR creation

Solution: Rename Branch

Step 1: Check current branch name

git branch --show-current

Step 2: Rename branch locally

# If current branch is: feature/user-authentication
# Rename to include task ID
git branch -m feature/user-authentication feature/CU-123abc-user-authentication

Step 3: Update remote branch

# Push renamed branch
git push origin -u feature/CU-123abc-user-authentication

# Delete old branch on remote (optional)
git push origin --delete feature/user-authentication

Step 4: Update PR (if already created) 1. GitHub automatically updates PR to track new branch name 2. Close and reopen PR to trigger workflow again 3. Or push a new commit to trigger workflow

Verification

# View GitHub Actions logs
gh run list --branch feature/CU-123abc-user-authentication

# Should see: "Found task ID: CU-123abc"

Valid Branch Name Formats

Correct examples:

feature/CU-123abc-user-login
fix/CU-456def-payment-bug
hotfix/CU-789ghi-critical-fix
refactor/CU-abc123-database-cleanup

Incorrect examples:

feature/123abc-description        # Missing CU- prefix
feature/user-login                # No task ID at all
CU-123abc-user-login              # Missing branch type prefix
feature/user-login-CU-123abc      # Task ID not after first slash

---

Issue 2: PR Targeting Wrong Branch

Symptoms

• GitHub Action not triggering when PR is created
• Workflow doesn't appear in Actions tab
• No status update in ClickUp

Root Causes

1. PR targets main instead of develop
2. Workflow configured for different branch than PR target
3. Branch name mismatch in workflow file

Solution: Change PR Base Branch

Check PR target branch:

# View PR details
gh pr view [PR-NUMBER]

# Look for: base: develop (should match workflow configuration)

Option 1: Change PR base branch (GitHub UI) 1. Go to PR page on GitHub 2. Click Edit button next to base branch 3. Select correct branch (e.g., develop) 4. GitHub will automatically re-trigger workflows

Option 2: Update workflow to match your branch

If your team uses main instead of develop, update workflows:

# Edit .github/workflows/clickup-pr-created.yml
on:
  pull_request:
    types: [opened, reopened]
    branches:
      - main  # Change from 'develop' to 'main'

Verification

1. Check GitHub Actions tab
2. Should see workflow run triggered after PR creation or base branch change
3. ClickUp task status should update within 10-20 seconds

---

Issue 3: GitHub Secret Not Accessible

Symptoms

• GitHub Action fails with "secret not found" error
• Log shows: CLICKUP_TOKEN: *** (empty or undefined)
• API calls return 401 Unauthorized

Root Causes

1. Secret created at repository level, workflow expects environment level
2. Environment name mismatch (development vs dev)
3. Branch not allowed to access environment
4. Typo in secret name

Solution: Verify Secret Configuration

Step 1: Check where secret is stored

# GitHub UI: Settings → Secrets and variables → Actions
# Look in two places:
# 1. Repository secrets
# 2. Environment secrets (under Environments)

Step 2: Match workflow configuration

If using environment secrets:

jobs:
  update-clickup:
    environment: development  # Must match environment name exactly
    steps:
      - name: Use secret
        env:
          CLICKUP_TOKEN: ${{ secrets.CLICKUP_TASKS_UPDATE_TOKEN }}

If using repository secrets:

jobs:
  update-clickup:
    # Remove 'environment: development' line
    runs-on: ubuntu-latest
    steps:
      - name: Use secret
        env:
          CLICKUP_TOKEN: ${{ secrets.CLICKUP_TASKS_UPDATE_TOKEN }}

Step 3: Verify environment access

If using environments: 1. Go to Settings → Environments → [Your Environment] 2. Check "Deployment branches" setting 3. Ensure your branch is allowed: - Option A: Selected branches → Add develop - Option B: All branches

Step 4: Verify secret name

Secret name must match exactly: - Correct: CLICKUP_TASKS_UPDATE_TOKEN - Incorrect: CLICKUP_TOKEN, CLICKUP_API_TOKEN

Verification

Test secret access:

# Add debug step to workflow (temporarily)
- name: Debug secret
  run: |
    if [ -z "${{ secrets.CLICKUP_TASKS_UPDATE_TOKEN }}" ]; then
      echo "ERROR: Secret is empty"
      exit 1
    else
      echo "SUCCESS: Secret is available"
    fi

---

Issue 4: ClickUp Status Not Updating

Symptoms

• GitHub Action completes successfully
• No error in logs
• ClickUp task status doesn't change

Root Causes

1. Task ID is incorrect or doesn't exist
2. Status name mismatch (case-sensitive)
3. ClickUp API token lacks permissions
4. Task is in different space/list than expected

Solution: Debug API Call

Step 1: Verify task exists

# Test ClickUp API access
curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/task/CU-123abc

# Should return task details, not 404 error

Step 2: Check status name

Status names are case-sensitive and must match exactly: - Correct: PR CREATED - Incorrect: pr created, PR Created, Pr Created

Verify in ClickUp: 1. Go to Space → Settings → Statuses 2. Note exact spelling and capitalization 3. Update workflow if needed

Step 3: Check API token permissions

Token must have: - Read access to tasks - Write access to tasks - Access to the specific space/list

Test token:

# List accessible teams
curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/team

# Should list teams you have access to

Step 4: Add detailed logging to workflow

- name: Update ClickUp status with debug
  run: |
    echo "Task ID: $TASK_ID"
    echo "Status: PR CREATED"

    RESPONSE=$(curl -s -w "\n%{http_code}" -X PUT \
      "https://api.clickup.com/api/v2/task/$TASK_ID" \
      -H "Authorization: $CLICKUP_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "status": "PR CREATED"
      }')

    HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
    BODY=$(echo "$RESPONSE" | head -n-1)

    echo "HTTP Code: $HTTP_CODE"
    echo "Response Body: $BODY"

    if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
      echo "Success"
    else
      echo "Failed"
      exit 1
    fi

Common API Error Codes

Code	Meaning	Solution
200	Success	Status updated successfully
400	Bad request	Check status name spelling
401	Unauthorized	Verify API token is correct
404	Not found	Task ID doesn't exist or no access
429	Rate limited	Wait and retry (see Issue 7)

---

Issue 5: Workflow Not Triggering

Symptoms

• PR created but no workflow run appears in Actions tab
• No logs in GitHub Actions
• Nothing happens in ClickUp

Root Causes

1. Workflow file in wrong location
2. YAML syntax error in workflow file
3. Workflow disabled
4. PR from forked repository

Solution: Verify Workflow Configuration

Step 1: Check file location

Workflows must be in:

.github/workflows/clickup-pr-created.yml
.github/workflows/clickup-pr-merged.yml

Not:

github/workflows/         # Missing dot
.github/workflow/         # Missing 's'
workflows/                # Wrong parent directory

Step 2: Validate YAML syntax

# Install yamllint (if not installed)
pip install yamllint

# Validate workflow file
yamllint .github/workflows/clickup-pr-created.yml

Or use online validator: https://www.yamllint.com/

Step 3: Check if workflow is enabled

1. Go to GitHub repository → Actions tab
2. Left sidebar: Find your workflow
3. If disabled, click "Enable workflow"

Step 4: Check workflow permissions

1. Go to Settings → Actions → General
2. Workflow permissions should be:
3. "Read and write permissions" (for adding comments)
4. Or "Read repository contents permissions" (minimum)

Step 5: Test workflow manually

Add manual trigger to workflow (temporarily):

on:
  workflow_dispatch:  # Allows manual triggering
  pull_request:
    types: [opened, reopened]
    branches:
      - develop

Then trigger manually: 1. Actions tab → Select workflow 2. "Run workflow" button 3. Check logs for errors

---

Issue 6: Automation Rules Not Firing

Symptoms

• ClickUp automation configured but not executing
• Expected action doesn't occur
• No automation log entries

Root Causes

1. Automation disabled
2. Trigger condition not met
3. Action condition prevents execution
4. Workspace plan doesn't support automations

Solution: Debug Automation

Step 1: Check if automation is enabled

1. Go to ClickUp Space → Automations
2. Find your automation in list
3. Toggle should be green (enabled)
4. If gray, click to enable

Step 2: Test trigger manually

For "PR opened" automation: 1. Manually change task status to "IN PROGRESS" 2. Change status to "PR CREATED" 3. Check if automation runs

Step 3: Review automation log

1. Space → Automations → Click automation
2. View "Activity" tab
3. Check recent executions
4. Look for errors or skipped runs

Step 4: Simplify automation

Remove conditions temporarily to isolate issue:

Before:
Trigger: Status changes to PR CREATED
Condition: PR Link is empty
Action: Move to IN PROGRESS

After (simplified):
Trigger: Status changes to PR CREATED
Condition: (none)
Action: Create comment "Automation triggered"

If simplified version works, issue is with condition logic.

Step 5: Check workspace plan

Automations require: - ClickUp Business plan or higher - Admin permissions in workspace

Verify: 1. Workspace settings → Plan & Billing 2. Confirm Business+ plan active

---

Issue 7: API Rate Limiting

Symptoms

• GitHub Actions fail intermittently
• HTTP 429 errors in logs
• Message: "Rate limit exceeded"

Root Causes

1. Too many API calls in short time
2. Multiple workflows triggering simultaneously
3. No retry logic for rate limits

Solution: Implement Rate Limit Handling

Step 1: Add retry logic to workflow

- name: Update ClickUp with retry
  env:
    CLICKUP_TOKEN: ${{ secrets.CLICKUP_TASKS_UPDATE_TOKEN }}
    TASK_ID: ${{ steps.extract-task-id.outputs.task_id }}
  run: |
    MAX_RETRIES=3
    RETRY_COUNT=0
    BACKOFF=10

    while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
      RESPONSE=$(curl -s -w "\n%{http_code}" -X PUT \
        "https://api.clickup.com/api/v2/task/$TASK_ID" \
        -H "Authorization: $CLICKUP_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"status": "PR CREATED"}')

      HTTP_CODE=$(echo "$RESPONSE" | tail -n1)

      if [ "$HTTP_CODE" -eq 429 ]; then
        echo "Rate limited. Waiting ${BACKOFF}s before retry..."
        sleep $BACKOFF
        BACKOFF=$((BACKOFF * 2))  # Exponential backoff
        RETRY_COUNT=$((RETRY_COUNT + 1))
      elif [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
        echo "Success"
        exit 0
      else
        echo "Failed with HTTP $HTTP_CODE"
        exit 1
      fi
    done

    echo "Max retries exceeded"
    exit 1

Step 2: Batch API calls

Combine multiple API calls into one where possible:

# Instead of: Update status + Add comment (2 calls)
# Do: Update status with comment in single call (if API supports)

Step 3: Monitor rate limit headers

curl -i -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/task/CU-123abc

# Check response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1234567890

---

Issue 8: Task Not Found (404 Error)

Symptoms

• API returns 404 error
• Log shows: "Failed to update ClickUp (HTTP 404)"
• Task exists in ClickUp UI

Root Causes

1. Task ID format incorrect
2. Task in different workspace
3. API token doesn't have access to task
4. Task was deleted/archived

Solution: Verify Task Access

Step 1: Extract task ID correctly

# ClickUp URL: https://app.clickup.com/t/CU-123abc
# Task ID for API: CU-123abc

# Some ClickUp instances use different prefixes
# Check your ClickUp URL format

Step 2: Test task access directly

# Try with CU- prefix
curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/task/CU-123abc

# If 404, try without prefix
curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/task/123abc

# Use whichever format returns 200

Step 3: Check task exists and is accessible

1. Open task in ClickUp UI
2. Copy URL from browser
3. Extract task ID from URL
4. Use exact format in workflow

Step 4: Verify API token has access

API token must: - Be created by user with access to task's workspace - Have permissions for the space containing task - Not be revoked or expired

Test:

# List accessible spaces
curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/team/[TEAM_ID]/space

# Verify task's space appears in list

---

Issue 9: Deployment Comment Not Adding

Symptoms

• PR merge works correctly
• Status updates to "MERGED & DEPLOYED DEV"
• But no deployment comment appears

Root Causes

1. Deployment workflow not triggered
2. Task ID not in commit message
3. API token expired
4. Comment API call failing silently

Solution: Debug Deployment Workflow

Step 1: Check if workflow triggered

# View recent workflow runs
gh run list --workflow=clickup-deployment-success.yml

# If no runs, workflow isn't triggering

Step 2: Verify commit message format

Workflow extracts task ID from commit message:

# Commit message must contain: CU-123abc

# Good examples:
git commit -m "feat: add login (CU-123abc)"
git commit -m "fix(CU-456def): resolve bug"

# Bad examples:
git commit -m "feat: add login"  # No task ID

Step 3: Test comment API manually

curl -X POST \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment_text": "Test comment"}' \
  https://api.clickup.com/api/v2/task/CU-123abc/comment

# Should return 200 and comment ID

Step 4: Check workflow logs

1. Go to Actions → clickup-deployment-success workflow
2. Click latest run
3. Expand "Add deployment comment" step
4. Look for errors or API failures

---

FAQ

Q: Do I need to manually link PRs to ClickUp tasks?

A: No. If your branch name contains the task ID (e.g., feature/CU-123abc-login), the automation extracts it automatically. No manual PR description editing required.

Q: Can I use task IDs without the "CU-" prefix?

A: It depends on your ClickUp configuration. Check your task URLs. If they show CU-123abc, use that format. Update the regex in workflows if your prefix is different:

# Change this line in workflows:
TASK_ID=$(echo "$BRANCH_NAME" | grep -oP 'CU-\w+' || echo "")

# To match your prefix (e.g., "TASK-"):
TASK_ID=$(echo "$BRANCH_NAME" | grep -oP 'TASK-\w+' || echo "")

Q: What happens if I close a PR without merging?

A: Nothing. The workflow only triggers on merged PRs (if: github.event.pull_request.merged == true). Closed but unmerged PRs won't update ClickUp.

Q: Can I use this integration with GitHub Enterprise?

A: Yes, but you may need to adjust API endpoints. Update GITHUB_API_URL if using self-hosted GitHub Enterprise.

Q: How do I debug webhook issues?

A: ClickUp GitHub App uses webhooks. Check: 1. GitHub → Settings → Webhooks 2. Find ClickUp webhook 3. Click to view recent deliveries 4. Check response codes and payloads

Q: What if my team uses a different main branch?

A: Update all workflow files to use your branch name:

branches:
  - main  # or master, or your branch name

Q: Can I test without creating real PRs?

A: Yes, use workflow_dispatch for manual testing:

on:
  workflow_dispatch:
    inputs:
      task_id:
        description: 'ClickUp Task ID'
        required: true
  pull_request:
    # ... existing config

Then trigger manually with test task ID.

---

Getting Help

When to Seek Help

Seek additional support if: - Issue persists after following troubleshooting steps - Error messages are unclear - API returns unexpected responses - Automation behavior is inconsistent

Where to Get Help

Internal resources: 1. Check Quick Start Guide for setup verification 2. Review Advanced Automation Guide for configuration 3. Ask in team Slack channel 4. Contact DevOps team

External resources: 1. ClickUp API documentation: https://clickup.com/api 2. GitHub Actions documentation: https://docs.github.com/actions 3. ClickUp support: [email protected] 4. GitHub support: support.github.com

Information to Provide When Asking for Help

Include: - Task ID experiencing issues - PR URL (if applicable) - GitHub Actions workflow run URL - Error messages from logs - Steps you've already tried - Expected vs actual behavior

---

Related Documentation

• GitHub-ClickUp Quick Start - Initial setup guide
• GitHub-ClickUp Advanced Automation - Custom fields and automation rules
• GitHub-ClickUp Workflow Guide - Daily usage patterns
• Git Workflow - Complete Git workflow