Skip to content

GitHub-ClickUp Integration: Advanced Automation

Configure advanced automation rules, custom fields, and deployment tracking

Time Required: - Team Lead: 20-25 minutes - One-time setup

Prerequisites: - Basic integration completed (see Quick Start Guide) - ClickUp workspace admin access - GitHub repository admin access - Understanding of your team's workflow

Overview

This guide covers advanced automation features that enhance your GitHub-ClickUp integration. You'll configure custom fields for bug tracking, create sophisticated automation rules, and set up deployment notifications.

What you'll configure: 1. Custom fields (Detection Phase, PR Link, Severity, Story Points, Reviewer) 2. Advanced ClickUp automation rules 3. Deployment success notifications 4. Custom status mappings 5. Best practices for automation

Prerequisites: - Complete Quick Start Guide first - Basic GitHub Actions and ClickUp automation knowledge

Part 1: Custom Fields Setup

Overview

Custom fields help you track important metadata for tasks, especially bugs. These fields enable better reporting and ensure consistent information capture.

Time: 10 minutes

Navigate to ClickUp List → Customize → Add Custom Field

Purpose: Track which pull request implements this task

  • Type: URL
  • Required: Yes (when status = "PR CREATED")
  • Description: "Link to GitHub pull request"

Why: Enables quick navigation from task to PR and vice versa.

Field 2: Detection Phase

Purpose: Track where bugs are discovered for quality metrics

  • Type: Dropdown
  • Options: Dev | QA | Production
  • Required: Yes (for bug subtasks)
  • Description: "Where was this bug detected?"

Why: Helps calculate bug escape rate and improve QA processes.

Field 3: Severity

Purpose: Prioritize bugs based on impact

  • Type: Dropdown
  • Options: Blocker | Critical | High | Medium | Low
  • Required: Yes (for bug subtasks)
  • Description: "Bug severity level"

Severity definitions: - Blocker: Prevents release, system down - Critical: Major feature broken, workaround exists - High: Important feature impaired - Medium: Minor feature issue - Low: Cosmetic or edge case

Field 4: Story Points

Purpose: Estimate task complexity for sprint planning

  • Type: Number
  • Options: 1, 2, 3, 5, 8, 13 (Fibonacci sequence)
  • Required: Yes (for planning)
  • Description: "Estimated complexity (Fibonacci)"

Estimation guide: - 1: Trivial change (< 1 hour) - 2: Simple task (1-2 hours) - 3: Standard task (2-4 hours) - 5: Complex task (1 day) - 8: Very complex (2-3 days) - 13: Needs breakdown (> 3 days)

Field 5: Reviewer

Purpose: Assign code reviewer explicitly

  • Type: Person
  • Required: No
  • Description: "Assigned code reviewer"

Why: Makes PR review responsibilities clear before PR is created.

Part 2: Advanced ClickUp Automations

Overview

These automation rules enforce workflow compliance and provide automated tracking. They complement the GitHub Actions workflows from the quick start guide.

Time: 10 minutes

Navigate to ClickUp Space → Automations → Create Automation

Purpose: Prevent status change to "PR CREATED" without PR link

Trigger: Task status changes to "PR CREATED"
Condition: PR Link custom field is empty
Action: Move back to IN PROGRESS + add comment

ClickUp Configuration: 1. Trigger: "When status changes to PR CREATED" 2. Condition: "Custom field 'PR Link' is empty" 3. Action 1: "Change status to IN PROGRESS" 4. Action 2: "Create comment: 'PR link required before moving to PR CREATED'" 5. Save

Why: Ensures tasks have PR links before marking as under review. This maintains traceability.

Note: ClickUp doesn't support "block transition" directly, so we move the task back and notify.

Automation 2: QA Approval Tracking

Purpose: Document who approved a task and when

Trigger: Task status changes to "DONE"
Condition: Previous status was "READY FOR QA"
Action: Add comment with QA approval timestamp

ClickUp Configuration: 1. Trigger: "When status changes to DONE" 2. Condition: "Previous status was READY FOR QA" 3. Action: "Create comment: 'QA Approved by [User] on [Date]'" 4. Save

Why: Creates audit trail of QA approvals for compliance and quality tracking.

Automation 3: Bug Subtask Enforcement

Purpose: Ensure bug subtasks have required fields

Trigger: Subtask created with "Bug:" in title
Condition: Detection Phase OR Severity is empty
Action: Assign to creator + add comment reminder

ClickUp Configuration: 1. Trigger: "When subtask is created" 2. Condition: "Title contains 'Bug:' AND (Detection Phase is empty OR Severity is empty)" 3. Action 1: "Assign to task creator" 4. Action 2: "Create comment: 'Please set Detection Phase and Severity for bug tracking'" 5. Save

Why: Maintains data quality for bug metrics and reporting.

Automation 4: Reviewer Notification

Purpose: Notify assigned reviewer when PR is created

Trigger: Task status changes to "PR CREATED"
Condition: Reviewer field is not empty
Action: Send notification to Reviewer

ClickUp Configuration: 1. Trigger: "When status changes to PR CREATED" 2. Condition: "Custom field 'Reviewer' is not empty" 3. Action: "Send notification to Reviewer: 'Please review PR for [Task Name]'" 4. Save

Why: Speeds up PR review process by notifying reviewers immediately.

Part 3: Deployment Tracking

Overview

Track deployment success and add environment URLs to tasks automatically. This workflow extends the basic integration to provide deployment visibility.

Time: 5 minutes

Workflow 3: Deployment Success Notification

File: .github/workflows/clickup-deployment-success.yml

name: ClickUp - Deployment Success

on:
  push:
    branches:
      - develop  # Trigger when code is pushed to develop (after PR merge)

jobs:
  update-clickup:
    runs-on: ubuntu-latest
    environment: development
    steps:
      - name: Extract ClickUp Task ID from latest commit
        id: extract-task-id
        run: |
          # Get the commit message from the push
          COMMIT_MSG="${{ github.event.head_commit.message }}"

          # Try to extract task ID from commit message
          TASK_ID=$(echo "$COMMIT_MSG" | grep -oP 'CU-\w+' || echo "")

          if [ -z "$TASK_ID" ]; then
            echo "No ClickUp task ID found in commit message"
            echo "This is normal for merges without task IDs"
            exit 0
          fi

          echo "task_id=$TASK_ID" >> $GITHUB_OUTPUT
          echo "Found task ID: $TASK_ID"

      - name: Wait for deployment to complete
        if: steps.extract-task-id.outputs.task_id != ''
        run: |
          echo "Waiting 30 seconds for deployment to complete..."
          sleep 30

      - name: Add deployment comment
        if: steps.extract-task-id.outputs.task_id != ''
        env:
          CLICKUP_TOKEN: ${{ secrets.CLICKUP_TASKS_UPDATE_TOKEN }}
          TASK_ID: ${{ steps.extract-task-id.outputs.task_id }}
        run: |
          DEPLOY_URL="https://dev.yourapp.com"  # Update with your dev URL
          COMMIT_SHA="${{ github.sha }}"
          SHORT_SHA="${COMMIT_SHA:0:7}"

          curl -s -X POST \
            "https://api.clickup.com/api/v2/task/$TASK_ID/comment" \
            -H "Authorization: $CLICKUP_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{
              \"comment_text\": \"Deployed to dev environment: $DEPLOY_URL\n\nCommit: $SHORT_SHA\nNext step: Verify on dev, then update status to READY FOR QA\"
            }"

          echo "Added deployment comment to task"

How it works: 1. Triggers when code is pushed to develop (after PR merge) 2. Extracts ClickUp task ID from commit message 3. Waits 30 seconds for deployment to complete 4. Adds deployment success comment with link to dev environment

Configuration: - Update DEPLOY_URL with your actual dev environment URL - Adjust sleep duration based on your deployment time - Modify branch name if you deploy from a different branch

Part 4: Custom Status Mappings

Overview

Customize status transitions based on your team's workflow. This section shows how to map different PR states to ClickUp statuses.

Standard Mapping

Default status flow: 

TODO → IN PROGRESS → PR CREATED → MERGED & DEPLOYED DEV → READY FOR QA → DONE

Alternative: Draft PR Support

If your team uses draft PRs, create additional status:

Additional Status: | Status Name | Color | Type | Description | |-------------|-------|------|-------------| | DRAFT PR | Light Purple | Custom | Work in progress, not ready for review |

Modified workflow: 

# Add to clickup-pr-created.yml
- name: Check if PR is draft
  id: check-draft
  run: |
    IS_DRAFT="${{ github.event.pull_request.draft }}"
    echo "is_draft=$IS_DRAFT" >> $GITHUB_OUTPUT

- name: Update to DRAFT PR if draft
  if: steps.check-draft.outputs.is_draft == 'true'
  run: |
    # Update status to DRAFT PR instead of PR CREATED
    # (use same API call but with "DRAFT PR" status)

- name: Update to PR CREATED if not draft
  if: steps.check-draft.outputs.is_draft == 'false'
  run: |
    # Update status to PR CREATED (existing logic)

Alternative: Staging Environment

If you deploy to staging before production:

Additional Status: | Status Name | Color | Type | Description | |-------------|-------|------|-------------| | DEPLOYED STAGING | Teal | Custom | Live on staging environment |

Additional workflow: 

# Create: .github/workflows/clickup-staging-deploy.yml
# Similar to deployment-success.yml but for staging branch

Part 5: Environment Variables and Secrets

Overview

Properly manage secrets and configuration for secure automation.

GitHub Secrets Required

Primary Secret: 

Name: CLICKUP_TASKS_UPDATE_TOKEN
Value: [Your ClickUp API token]
Location: GitHub Environment or Repository Secrets

Additional Secrets (Optional): 

Name: CLICKUP_SPACE_ID
Value: [Your ClickUp space ID]
Purpose: For space-level API calls

Name: CLICKUP_LIST_ID
Value: [Your ClickUp list ID]
Purpose: For creating tasks via API

Environment Variables in Workflows

Commonly customized variables: 

env:
  DEFAULT_STATUS: "PR CREATED"       # Status when PR opens
  MERGED_STATUS: "MERGED & DEPLOYED DEV"  # Status when PR merges
  DEPLOY_URL: "https://dev.yourapp.com"   # Your dev environment URL
  DEPLOY_WAIT_TIME: "30"             # Seconds to wait for deployment

How to customize: 1. Open workflow file 2. Update environment variables at job or step level 3. Commit changes

Best Practices

Secret Management: - Use GitHub Environments for multi-environment setup (dev/staging/prod) - Rotate ClickUp API tokens every 90 days - Never commit secrets to code - Use least-privilege tokens (don't use admin tokens)

Token Permissions: - ClickUp API token needs: Tasks (read/write), Comments (write) - GitHub token (if used): repos, workflow

Part 6: ClickUp API Integration

Overview

Advanced API usage for custom integrations beyond GitHub Actions.

Common API Endpoints

Get task details: 

curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/task/[TASK_ID]

Update task status: 

curl -X PUT \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "READY FOR QA"}' \
  https://api.clickup.com/api/v2/task/[TASK_ID]

Add comment: 

curl -X POST \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment_text": "Deployment successful"}' \
  https://api.clickup.com/api/v2/task/[TASK_ID]/comment

Update custom field: 

curl -X POST \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "https://github.com/org/repo/pull/123"}' \
  https://api.clickup.com/api/v2/task/[TASK_ID]/field/[FIELD_ID]

Rate Limiting

ClickUp API limits: - Free plan: 100 requests per minute - Unlimited plan: 100 requests per minute - Enterprise plan: Higher limits (contact ClickUp)

Best practices: - Batch API calls when possible - Use webhooks instead of polling - Cache responses for read operations - Implement exponential backoff on rate limit errors

Error Handling

Common status codes: - 200: Success - 400: Bad request (check payload format) - 401: Unauthorized (check token) - 404: Task not found (check task ID) - 429: Rate limited (wait and retry)

Retry logic example: 

- name: Update ClickUp with retry
  run: |
    MAX_RETRIES=3
    RETRY_COUNT=0

    while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
      RESPONSE=$(curl -s -w "\n%{http_code}" -X PUT ...)
      HTTP_CODE=$(echo "$RESPONSE" | tail -n1)

      if [ "$HTTP_CODE" -eq 429 ]; then
        echo "Rate limited, waiting 60 seconds..."
        sleep 60
        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

Part 7: Best Practices

Automation Design

Do: - Keep automations simple and focused - Test automations thoroughly before enabling for team - Document custom automations in ClickUp descriptions - Use clear naming conventions for automations - Monitor automation failures weekly

Don't: - Create circular automation loops (A triggers B triggers A) - Override manual status changes automatically - Create too many automations (overwhelming for team) - Skip testing automation changes

Workflow Optimization

Performance tips: - Use environment-level secrets for faster secret access - Minimize API calls in GitHub Actions (combine when possible) - Cache task IDs to reduce lookups - Use webhooks for real-time updates instead of polling

Team adoption: - Train team on branch naming requirements - Share examples of successful workflow usage - Create troubleshooting runbook for common issues - Collect feedback and iterate on automations

Monitoring

What to monitor: - GitHub Actions success rate (should be > 95%) - ClickUp automation execution count (check for failures) - PR to deployment time (should decrease over time) - Status transition compliance (are required fields filled?)

How to monitor: - GitHub Actions tab: Check workflow run history - ClickUp Automations: View automation logs - Create ClickUp dashboard for task metrics - Set up Slack notifications for automation failures

Verification Checklist

After completing advanced setup, verify:

  • [ ] All 5 custom fields created and visible in tasks
  • [ ] Custom fields are required in appropriate scenarios
  • [ ] 4+ automation rules configured and enabled
  • [ ] Deployment success workflow tested
  • [ ] Custom status mappings (if any) working correctly
  • [ ] API rate limiting handled in workflows
  • [ ] Team trained on custom fields usage
  • [ ] Documentation updated for custom automations
  • [ ] Monitoring dashboard created
  • [ ] Backup of automation configurations saved

Maintenance

Weekly

  • Review GitHub Actions failure logs
  • Check ClickUp automation execution history
  • Verify no API rate limiting issues

Monthly

  • Rotate ClickUp API tokens (recommended every 90 days)
  • Update automation rules based on team feedback
  • Review custom field usage and adjust requirements
  • Clean up unused custom fields and automations

Quarterly

  • Re-test full integration flow
  • Update workflows for new features
  • Review and optimize API usage
  • Document lessons learned and update guides