GitHub-ClickUp Integration: Quick Start

Get up and running in 20 minutes with core integration features

Time Required: - Team Admin: 15 minutes - Developer: 5 minutes - Total: 20 minutes one-time setup

Prerequisites: - ClickUp workspace admin access - GitHub organization admin access - ClickUp API token - GitHub personal access token

Overview

This quick start guide walks you through setting up the essential GitHub-ClickUp integration. You'll configure automated status updates when PRs are created and merged.

What you'll set up: 1. ClickUp GitHub App (official integration) 2. Basic GitHub Actions workflows (status updates) 3. Simple verification

What's NOT covered here: - Advanced automation rules (see Advanced Automation Guide) - Custom fields configuration (see Advanced Automation Guide) - Troubleshooting (see Troubleshooting Guide)

Step 1: Install ClickUp GitHub App

Time: 5 minutes

Go to ClickUp workspace settings
Click Integrations → GitHub
Click Connect to GitHub
Authorize ClickUp to access your GitHub organization
Select repositories to integrate:
Option A: All repositories (recommended)
Option B: Specific repositories (select each project repo)
Click Install & Authorize

Expected Result: You'll see "GitHub connected" in ClickUp integrations page

Verify Permissions

Time: 2 minutes

Verify the ClickUp GitHub App has these permissions: - Read access to repository code - Read access to pull requests - Read access to issues - Write access to pull request comments (optional)

How to check: 1. Go to GitHub → Settings → Applications → ClickUp 2. Review permissions 3. If missing, re-authorize with additional permissions

Step 2: Create Basic ClickUp Statuses

Time: 3 minutes

Navigate to ClickUp Space → Settings → Statuses

Create these core statuses:

Status Name	Color	Type	Description
TODO	Gray (#D3D3D3)	Open	Ready for development
IN PROGRESS	Blue (#0000FF)	Custom	Active development
PR READY	Purple (#800080)	Custom	Awaiting review
PR MERGED	Yellow (#FFD700)	Custom	Merged to develop
READY FOR QA	Orange (#FFA500)	Custom	QA testing
DONE	Green (#00FF00)	Closed	QA approved

Status Flow:

TODO → IN PROGRESS → PR READY → PR MERGED → READY FOR QA → DONE

Step 3: Set Up GitHub Actions

Create ClickUp API Token

Time: 3 minutes

Go to ClickUp → Settings → Apps → API Tokens
Click Generate New Token
Name: "GitHub Actions Integration"
Copy token (save this for next step)

Security: Store token in GitHub Secrets (never commit to code)

Add GitHub Secret

Time: 2 minutes

Option 1: Environment Secret (Recommended) 1. Go to GitHub repository → Settings → Environments 2. Click New environment 3. Name: development 4. Click Add secret 5. Add secret:

Name: CLICKUP_TASKS_UPDATE_TOKEN
Value: [your token from previous step]

Option 2: Repository Secret (Alternative) 1. Go to GitHub repository → Settings → Secrets and variables → Actions 2. Click New repository secret 3. Add secret (same name and value as above)

Note: If using repository secrets, remove environment: development from workflows below.

Create GitHub Actions Workflows

Time: 8 minutes

Create these two workflow files in .github/workflows/ directory:

Workflow 1: PR Ready

File: .github/workflows/clickup-pr-created.yml

name: ClickUp - PR Ready

on:
  pull_request:
    types: [opened, reopened]
    branches:
      - develop  # Only trigger for PRs targeting develop branch

jobs:
  update-clickup:
    runs-on: ubuntu-latest
    environment: development  # Required for environment secrets
    steps:
      - name: Extract ClickUp Task ID from branch
        id: extract-task-id
        run: |
          BRANCH_NAME="${{ github.head_ref }}"
          TASK_ID=$(echo "$BRANCH_NAME" | grep -oP 'CU-\w+' || echo "")

          if [ -z "$TASK_ID" ]; then
            echo "No ClickUp task ID found in branch name: $BRANCH_NAME"
            echo "Expected format: feature/CU-123abc-description"
            exit 0  # Don't fail the workflow, just skip
          fi

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

      - name: Update ClickUp status to PR READY
        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: |
          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 READY"
            }')

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

          if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
            echo "Successfully updated task $TASK_ID to PR READY"
          else
            echo "Failed to update ClickUp (HTTP $HTTP_CODE)"
            echo "Response: $BODY"
            exit 1
          fi

      - name: Add PR link to ClickUp task
        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 }}
          PR_URL: ${{ github.event.pull_request.html_url }}
        run: |
          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\": \"PR Ready (targeting develop): $PR_URL\"
            }"

          echo "Added PR link to task"

How it works: 1. Triggers when PR is opened to develop branch 2. Extracts ClickUp task ID from branch name (format: CU-123abc) 3. Updates task status to "PR READY" 4. Adds PR link as comment

Workflow 2: PR Merged

File: .github/workflows/clickup-pr-merged.yml

name: ClickUp - PR Merged to Develop

on:
  pull_request:
    types: [closed]
    branches:
      - develop  # Only trigger for PRs merged to develop branch

jobs:
  update-clickup:
    # Only run if PR was actually merged (not just closed)
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    environment: development
    steps:
      - name: Extract ClickUp Task ID from branch
        id: extract-task-id
        run: |
          BRANCH_NAME="${{ github.head_ref }}"
          TASK_ID=$(echo "$BRANCH_NAME" | grep -oP 'CU-\w+' || echo "")

          if [ -z "$TASK_ID" ]; then
            echo "No ClickUp task ID found in branch name: $BRANCH_NAME"
            exit 0
          fi

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

      - name: Update ClickUp status to PR MERGED
        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: |
          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 MERGED"
            }')

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

          if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
            echo "Successfully updated task $TASK_ID to PR MERGED"
          else
            echo "Failed to update ClickUp (HTTP $HTTP_CODE)"
            echo "Response: $BODY"
            exit 1
          fi

      - name: Add merge 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: |
          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\": \"Merged to develop branch. Auto-deployment to dev environment initiated.\"
            }"

          echo "Added merge comment to task"

How it works: 1. Triggers when PR is merged to develop branch 2. Extracts ClickUp task ID from branch name 3. Updates task status to "MERGED & DEPLOYED DEV" 4. Adds merge notification comment

Step 4: Test the Integration

Time: 5 minutes

Test: PR Ready

Create test task in ClickUp (note the task ID, e.g., CU-test123)
Move task to "IN PROGRESS"

Create branch with task ID in name:

git checkout -b feature/CU-test123-test-integration

Make code change, commit, push:

echo "test" > test.txt
git add test.txt
git commit -m "feat: test GitHub-ClickUp integration"
git push origin feature/CU-test123-test-integration

Create PR on GitHub targeting develop branch
Wait 10-20 seconds for GitHub Action to run
Verify in ClickUp:
Task status changed to "PR READY"
Comment added with PR link

Test: PR Merged

Approve and merge the test PR into develop branch
Wait 10-20 seconds for GitHub Action to run
Check ClickUp task
Verify:
Task status changed to "PR MERGED"
Comment added: "Merged to develop branch..."

Expected Result: Both status transitions work automatically!

Branch Naming Convention

Critical: Your branch names must include the ClickUp task ID for automation to work.

Format: <type>/CU-<task-id>-<brief-description>

Valid examples:

feature/CU-123abc-user-authentication
fix/CU-456def-login-safari-bug
hotfix/CU-789ghi-payment-timeout

Invalid examples (automation won't work):

feature/user-authentication           # Missing task ID
feature/123abc-description            # Missing CU- prefix
CU-123abc-user-authentication         # Missing type prefix

Where to find task ID: 1. Open task in ClickUp 2. Look at URL bar: https://app.clickup.com/t/CU-123abc 3. Or see task ID in task header

Quick Reference

Status Flow

TODO → IN PROGRESS → PR READY → PR MERGED → READY FOR QA → DONE

What's Automated

PR opened → Status changes to "PR READY"
PR merged → Status changes to "PR MERGED"
PR link added as comment automatically

What's Manual

Moving task from TODO to IN PROGRESS (you start work)
Moving task from PR MERGED to READY FOR QA (after dev verification)
Moving task from READY FOR QA to DONE (after QA approval)

Next Steps

You've completed the basic setup! Here's what to do next:

Set up advanced automation - Configure custom fields, additional automation rules, and deployment notifications: Advanced Automation Guide
Learn daily workflow - Understand how to use the integration day-to-day: Workflow Guide
Troubleshooting - Bookmark for when things go wrong: Troubleshooting Guide

GitHub-ClickUp Advanced Automation - Custom fields, deployment notifications, and advanced rules
GitHub-ClickUp Troubleshooting - Debug common integration issues
GitHub-ClickUp Workflow Guide - Daily usage patterns
Git Branch Naming - Detailed branch naming standards