Skip to content

GitHub-ClickUp Integration: Daily Workflow Guide

Complete developer-to-QA lifecycle with automated status tracking

Time per task: ~20 seconds (using branch creation from ClickUp) Frequency: Every development task Goal: Zero manual status updates, minimal manual task ID entry

Complete Development Lifecycle

This diagram shows the entire flow from task assignment to QA approval, including automated and manual steps.

flowchart TD
    Start[Task Assigned to Developer] --> Understand[Developer Reviews Task]
    Understand --> InProgress[Update ClickUp: IN PROGRESS]

    InProgress --> Branch{Create Branch}
    Branch -->|Option A: ClickUp Button| BranchA[ClickUp Generates Branch]
    Branch -->|Option B: Manual| BranchB[Create with CU-id Format]
    BranchA --> Develop[Development Work]
    BranchB --> Develop

    Develop --> LocalTest[Test Locally]
    LocalTest --> ReadyPR{Ready for PR?}
    ReadyPR -->|No| Develop
    ReadyPR -->|Yes| PRChoice{Choose PR Type}

    PRChoice -->|Draft PR<br/>Work in progress| DraftPR[Create Draft PR]
    DraftPR -->|GitHub Actions| PRDrafted[AUTO: PR DRAFTED]
    PRDrafted --> ConvertReady{Ready for Review?}
    ConvertReady -->|No - More work| Develop
    ConvertReady -->|Yes - Convert| ConvertOpen[Mark as Open]
    ConvertOpen -->|GitHub Actions| PRReady[AUTO: PR READY]

    PRChoice -->|Open PR<br/>Ready to merge| OpenPR[Create Open PR]
    OpenPR -->|GitHub Actions| PRReady

    PRReady --> CodeReview[Code Review]
    CodeReview --> ReviewDecision{Approved?}
    ReviewDecision -->|Changes Needed| Develop
    ReviewDecision -->|Approved| Merge[Merge PR]

    Merge -->|GitHub Actions| PRMerged[AUTO: PR MERGED]
    PRMerged -->|Auto-Deploy<br/>5-10 minutes| DevEnv[Deployed to Dev Environment]

    DevEnv --> DevTest[Developer Tests on Dev]
    DevTest --> DevWorks{Works Correctly?}
    DevWorks -->|No - More Changes| Develop
    DevWorks -->|Yes| ReadyQA[Developer: Update to READY FOR QA]

    ReadyQA --> QAStarts[QA: Update to UNDER TESTING]
    QAStarts --> QATest[QA Tests Feature]
    QATest --> QADecision{Issues Found?}

    QADecision -->|Yes - Assign Back| QAIssues[Add Comments & Assign to Dev]
    QAIssues --> InProgress

    QADecision -->|No Issues| Done[QA: Mark as DONE]

    style PRDrafted fill:#FFF9C4,stroke:#F57C00
    style PRReady fill:#90EE90,stroke:#2E7D32
    style PRMerged fill:#90EE90,stroke:#2E7D32
    style Done fill:#4CAF50,stroke:#2E7D32,color:#fff
    style DevEnv fill:#FFF9C4,stroke:#F57C00
    style InProgress fill:#E3F2FD,stroke:#1976D2
    style ReadyQA fill:#F3E5F5,stroke:#7B1FA2
    style QAStarts fill:#FCE4EC,stroke:#C2185B

Timeline Overview

Phase Duration Status Updates Automated?
Development Varies IN PROGRESS Manual
Draft PR (Optional) Varies PR DRAFTED Automated
PR Review Hours-Days PR READY Automated
Merge & Deploy 5-10 min PR MERGED Automated
Dev Testing Minutes-Hours READY FOR QA Manual
QA Testing Hours-Days UNDER TESTING → DONE Manual

Automated vs Manual Steps

Fully Automated (GitHub Actions): - Draft PR Created → Task updates to "PR DRAFTED" - Draft PR Converted to Open → Task updates to "PR READY" - Open PR Created → Task updates to "PR READY" - PR Merged → Task updates to "PR MERGED" - Code deployment to dev environment (5-10 minutes)

Manual Updates Required: - Task assignment → IN PROGRESS - After dev testing → READY FOR QA - QA starts → UNDER TESTING - QA completes → DONE - QA finds issues → Assign back to developer

Your Current Step

Find where you are in the workflow and what comes next!

Quick Reference

Action Time Method
Create branch with task ID 10 sec Create from ClickUp task
Auto-update status on commit 0 sec Use #CU-abc123[status] syntax
PR merged → status update 0 sec Automatic
Deploy → Ready for QA 0 sec Automatic (GitHub Actions)

Total manual work: ~10-20 seconds per task

Creating Your Branch

You have two options for creating a branch with the correct ClickUp task ID:

  1. Open your task in ClickUp
  2. Click the "Create Branch" button in the task details
  3. ClickUp automatically generates branch name: feature/CU-{id}-{description}
  4. Copy the branch name
  5. In your terminal: 
    git fetch
git checkout feature/CU-abc123-your-feature

Benefits: - Guaranteed correct format - Task ID automatically included - Branch name matches task title - No manual typing needed

Option B: Manual Branch Creation

  1. Note your task ID from ClickUp URL or task details (e.g., CU-86evg8jk0)
  2. Create branch locally: 
    git checkout develop
git pull origin develop
git checkout -b feature/CU-86evg8jk0-your-description

Requirements: - Must include CU-{id} somewhere in branch name - Follow naming convention: feature/CU-{id}-{description} - Use kebab-case for description

Both options work with GitHub Actions automation!

Core Concept: Task ID Linking

The Only Method: Include ClickUp task ID in GitHub activity

Task ID Formats: - #abc123 (short form) - CU-abc123 (full form, recommended) - eng-123 (custom prefix, if configured)

Where to Include Task ID: 1. Branch name (automatic if created from ClickUp) 2. Commit message 3. PR title 4. PR description

Status Update Syntax: 

#CU-abc123[in review]  → Changes task to "In Review"
#CU-abc123[closed]     → Marks task as "Closed"

Goal: Create branch with auto-included task ID

Steps:

  1. Open ClickUp task (5 sec)

  2. Press Cmd+K → search task → Enter

  3. Click GitHub icon (2 sec)

  4. In task sidebar, click GitHub icon

  5. See suggested branch names

  6. Create branch (3 sec)

  7. Click "New GitHub Branch"
  8. Branch name auto-populated: CU-abc123-feature-name
  9. Select repository

  10. Click "Create"

  11. Pull branch locally 

    git fetch
git checkout CU-abc123-feature-name

Total time: ~10 seconds Task ID: Automatically included ✅

Method B: Manual Branch Creation

If you prefer terminal workflow:

# Get task ID from ClickUp (click to copy)
git checkout -b feature/CU-abc123-user-dashboard

Branch naming convention: 

feature/CU-{taskId}-{description}
fix/CU-{taskId}-{bug-description}
hotfix/CU-{taskId}-{critical-fix}

Workflow 2: Committing with Status Updates

Goal: Link commits to task AND update status

git commit -m "Add user dashboard CU-abc123"

Result: Commit linked to task, status unchanged

Commit with Status Update

git commit -m "Complete user dashboard #CU-abc123[in review]"

Result: Commit linked AND task status → "In Review"

Status Update Options

Syntax Result
#CU-abc123[in progress] Status → "In Progress"
#CU-abc123[pr ready] Status → "PR Ready"
#CU-abc123[in review] Status → "In Review"
#CU-abc123[ready] Status → "Ready for QA"
#CU-abc123[closed] Status → "Closed/Done"

Note: Status name must match your ClickUp status exactly (case-insensitive)

Workflow 3: Creating Pull Request

Goal: Link PR and auto-update task status

Step 1: Push Branch

git push origin feature/CU-abc123-user-dashboard

Step 2: Create PR with Task Reference

Option A: PR Title (Most Visible) 

Add user analytics dashboard (#CU-abc123)

Option B: PR Description 

## Description
Implements user analytics dashboard

## ClickUp Task
Closes #CU-abc123

## Testing
- [x] Unit tests passing
- [x] Manual testing complete

Option C: PR Title + Status Update 

Add user analytics dashboard #CU-abc123[in review]

Step 2.5: Choose PR State (Draft or Open)

Important: Choose the appropriate PR state based on readiness:

Use Draft PR when:

  • ❌ Work is still in progress
  • ❌ You want early feedback on approach (not ready for formal review)
  • ❌ Need to run CI/CD tests first
  • ❌ Code is not ready to be merged

Use Open PR (Ready for Review) when:

  • ✅ All work is complete and ready to be merged
  • ✅ Code can be formally reviewed immediately
  • ✅ All tests are passing
  • ✅ Ready for team lead approval

Why this matters: - Reviewers prioritize Open PRs over drafts - Prevents wasted reviewer time on incomplete work - Clearly communicates readiness status to the team - ClickUp automation updates task status accordingly

How to set PR state:

Create as Draft: 

On GitHub PR creation page:
Click "Create draft pull request" (green dropdown arrow)

Create as Open (default): 

On GitHub PR creation page:
Click "Create pull request" (green button)

Convert Draft to Open: 

When work is ready:
Click "Ready for review" button at top of PR

ClickUp Status Mapping: - Draft PR → Task status: "PR DRAFTED" - Open PR → Task status: "PR READY"

Step 3: Verify Auto-Update (5-10 seconds)

  1. Wait 5-10 seconds
  2. Check ClickUp task
  3. Verify:
  4. ✅ PR link appears in task sidebar
  5. ✅ Task status changed to "PR Ready" (or specified status)
  6. ✅ PR info visible (reviews, checks, etc.)

Workflow 4: Code Review to Merge

What Happens Automatically:

  1. Reviewer approves PR → No status change (stays "PR Ready")
  2. PR merged → Task status changes to "Merged & Deployed Dev" (automatic)
  3. Deploy succeeds → Task status changes to "Ready for QA" (GitHub Actions)

Developer adds context: (30 sec)

@QA Ready for testing!

**Environment:** dev.azmx.com/dashboard
**Test user:** [email protected]
**Focus areas:**
- Analytics charts rendering
- Mobile responsiveness
- Error handling

**Known issues:** None

Total manual work: 30 seconds

What Happens After PR Merge

Automatic Deployment Timeline

graph LR
    A[0 min<br/>PR Merged] --> B[1-3 min<br/>Deployment Starts]
    B --> C[5-10 min<br/>Live on Dev]
    C --> D[+15 min<br/>Developer Tests]
    D --> E[+30 min<br/>READY FOR QA]

    style A fill:#E3F2FD,stroke:#1976D2
    style B fill:#FFF9C4,stroke:#F57C00
    style C fill:#C8E6C9,stroke:#388E3C
    style D fill:#F3E5F5,stroke:#7B1FA2
    style E fill:#4CAF50,stroke:#2E7D32,color:#fff

Timeline Details: - 0 min: PR merged, GitHub Actions updates ClickUp to "PR MERGED" - 1-3 min: Deployment starts, code building and deploying - 5-10 min: Live on dev environment, changes are testable - +15 min: Developer tests and verifies changes work correctly - +30 min: Update to READY FOR QA, QA team can start testing

Your Next Steps After Merge

  1. Wait 5-10 minutes for automatic deployment to dev environment
  2. Access dev environment (URL: https://dev.yourdomain.com or as configured)
  3. Test your changes:
  4. Verify feature works as expected
  5. Check for any unexpected side effects
  6. Test edge cases
  7. If everything works:
  8. Go to ClickUp
  9. Manually update task status to "READY FOR QA"
  10. Add testing notes in comments (optional but helpful)
  11. If issues found:
  12. Create new branch for fixes
  13. Repeat PR cycle
  14. Don't update to READY FOR QA until fixed

Note: Deployment is automatic but status update to "READY FOR QA" is manual - this ensures you've actually tested your changes before handing to QA.

Workflow 5: Bug Subtasks with Detection Phase

Goal: Track bugs, link to parent, tag for KPI metrics

Step 1: From Parent Task (3 sec)

  1. Open ClickUp task being tested
  2. Press T (creates subtask)

Step 2: Fill Bug Details (20 sec)

Title: Bug: Login button not working on Safari

Required Custom Fields: - Detection Phase: Dev | QA | Production (critical for KPIs) - Severity: Blocker | Critical | High | Medium | Low

Description: 

**Steps to Reproduce:**
1. Open login page in Safari
2. Enter valid credentials
3. Click login button

**Expected:** User logs in
**Actual:** No response

**Browser:** Safari 17.0 / macOS
**Environment:** dev.azmx.com

Total time: ~23 seconds

QA Testing & Rework Cycle

Happy Path: No Issues Found

graph LR
    A[READY FOR QA] --> B[QA: UNDER TESTING]
    B --> C[QA Tests Feature]
    C --> D[No Issues Found]
    D --> E[DONE]

    style E fill:#4CAF50,color:#fff

QA Process: 1. QA team sees task in "READY FOR QA" status 2. QA updates task to "UNDER TESTING" when starting 3. Tests feature thoroughly in dev environment 4. If everything works → Updates task to "DONE"

Rework Path: Issues Found

graph LR
    A[UNDER TESTING] --> B[QA Finds Issues]
    B --> C[Add Comments to Task]
    C --> D[Assign Back to Developer]
    D --> E[Developer: IN PROGRESS]
    E --> F[Fix Issues]
    F --> G[Repeat Cycle]

    style B fill:#FF5252,color:#fff

Rework Process: 1. QA finds bugs or issues during testing 2. QA adds detailed comments to ClickUp task: - What doesn't work - Steps to reproduce - Expected vs actual behavior - Screenshots if applicable 3. QA assigns task back to original developer 4. Task returns to "IN PROGRESS" status 5. Developer receives ClickUp notification 6. Developer fixes issues and repeats the entire cycle from step 3

Average Iterations

  • Simple features: 1 iteration (no rework)
  • Medium complexity: 1-2 iterations
  • Complex features: 2-3 iterations

Tip: Thorough dev environment testing (step 7) reduces QA rework cycles!

Workflow 6: Creating Branch from ClickUp

Why: Task ID automatically included, no copy-paste

Using GitHub Icon in Task

  1. Click GitHub icon in task sidebar
  2. See "Quick Start" section
  3. View suggested:
  4. Branch names (click to copy)
  5. Commit message templates

  6. Task ID

  7. Click "New GitHub Branch"

  8. Fill details:
  9. Branch name: Auto-populated with task ID
  10. Repository: Select from list
  11. Source branch: Usually main or develop
  12. Click "Create"

Custom Branch Format (Optional):

Set in ClickUp → App Center → GitHub → Workspace Settings: 

:taskId:_:taskName:_:username:

Example output: CU-ae27de_Auto-generated-naming_John-smith

Monthly KPI Reporting

Goal: Calculate bug detection rate

Time: 5 minutes monthly Owner: Tech Lead or QA Lead

Step 1: Create Saved Filter (one-time)

  1. ClickUp List view → "Filter"
  2. Configure:
  3. Title contains: "Bug:"
  4. Created date: Last month
  5. Has custom field: "Detection Phase"
  6. Save as: "Bugs - Last Month"

Step 2: Run Report (5 min)

  1. Open "Bugs - Last Month" filter
  2. Group by: "Detection Phase"
  3. Count bugs:
Detection Phase Count
Dev 12 ✅
QA 8 ✅
Production 2 ❌
Total 22

Step 3: Calculate KPI

Bug Detection Rate = (Dev + QA) / Total × 100
= (12 + 8) / 22 × 100 = 91%

Target: ≥90%

Keyboard Shortcuts

ClickUp

Action Shortcut
Open command menu Cmd+K
Create task C (List view)
Create subtask T (Task view)
Change status U (Task view)
Copy task ID Click ID in task

GitHub

Action Shortcut
Go to pull requests G → P
Submit review Cmd+Enter

Troubleshooting

Issue: Task Not Linking

Check: 1. Task ID format correct? (#CU-abc123 or CU-abc123) 2. Task in Space linked to repo? 3. GitHub App authorized?

Quick fix: 1. Manually add PR link to ClickUp task 2. Report to DevOps

Issue: Status Not Updating

Check: 1. Status syntax correct? [in review] not [inreview] 2. Status name matches ClickUp exactly? 3. No space between task ID and [status]?

Example: 

✅ Correct: #CU-abc123[in review]
❌ Wrong: #CU-abc123 [in review]  (space)
❌ Wrong: #CU-abc123[inreview]    (wrong name)

Best Practices

DO:

  • ✅ Create branches FROM ClickUp (auto task ID)
  • ✅ Use status syntax in commits: #CU-abc123[status]
  • ✅ Include task ID in PR title (most visible)
  • ✅ Set Detection Phase on ALL bug subtasks
  • ✅ Copy suggested branch names from ClickUp

DON'T:

  • ❌ Manually type task IDs (copy from ClickUp)
  • ❌ Skip status syntax (saves manual update)
  • ❌ Forget Detection Phase (breaks KPI tracking)
  • ❌ Create bugs as separate tasks (use subtasks)

Time Savings

Without Integration

Task Time
Create branch, manually add task ID 15 sec
Commit 5 sec
Create PR, manually reference task 20 sec
Manually update to "PR Ready" 15 sec
Manually update after merge 15 sec
Manually update after deploy 15 sec
Manually notify QA 10 sec
Total 95 sec

With Integration (Using Branch Creation)

Task Time
Create branch FROM ClickUp 10 sec
Commit with status syntax 5 sec
Create PR (task ID in branch) 15 sec
~~Update status~~ 0 sec (auto)
~~Update after merge~~ 0 sec (auto)
~~Update after deploy~~ 0 sec (auto)
Add QA notes 15 sec
Total 45 sec

Time saved: 50 seconds per task For 100 tasks/month: 83 minutes saved Annual: ~17 hours of manual status updates eliminated

Advanced: GitHub Automations

ClickUp offers "GitHub Automations" for advanced workflows (requires Business Plan+).

Example automations: - PR labeled "hotfix" → Set priority to Urgent - PR merged to main → Add comment with deploy link - Commit pushed → Update assignee

Setup: ClickUp → Automations → Create → Select GitHub trigger

See: Use GitHub Automations (ClickUp docs)

In this repository: - Quick Start Guide - 20-minute setup guide - Automation Guide - Advanced automation rules - Troubleshooting Guide - Debug common issues

In Vault (strategic): - Development Process Workflow - Complete process framework - Developer Quality Metrics Framework - KPI definitions - ClickUp for Team Coordination - Tool philosophy

External: - GitHub Integration (official docs) - Use GitHub Automations

Last Updated: 2025-11-10 Based on: Official ClickUp documentation (Nov 2025) Maintained By: Tech Leads