Vadym/obsidian
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
obsidian/01 Projects/DevOps_Click_UP_sync/USER_MANUAL.md
Vadym Samoilenko cf1bd1328b vault backup: 2026-05-18 18:40:34
2026-05-18 18:40:34 +01:00

3.8 KiB
Raw Permalink Blame History

auto_generated created manual_updated_at modified name status tags type
true 2026-05-18 2026-05-18 2026-05-18 User_Manual active
domain/devops
status/active
tech/azure-ad
tech/docker
tech/fastapi
type/sop
sop

DevOps ↔ ClickUp Sync User Manual

What This Tool Does

The DevOps ↔ ClickUp Sync service is an automated bridge between Microsoft Azure DevOps (ADO) and ClickUp. It synchronizes work items (tasks, bugs, epics) and their associated comments between the two platforms in real-time.

Key Capabilities:

  • Bidirectional Sync: Updates made in ADO are reflected in ClickUp, and vice versa.
  • Comment Sync: Comments added in either platform are pushed to the other.
  • Mapping Management: Automatically links corresponding IDs between ADO Work Items and ClickUp Tasks.
  • Dashboard Visibility: Provides a real-time status overview of sync operations.

Who Uses It

  • Project Managers: Who need to track progress in ClickUp while developers work in Azure DevOps.
  • Developers: Who need visibility into task statuses managed by their PMs in ClickUp.
  • DevOps Engineers: Who automate the synchronization pipeline.

How to Access

1. Web Dashboard

Access the user interface via your configured public URL:

  • URL: https://your-domain.com (or http://localhost:8080 if running locally)
  • Features: View sync status, recent logs, and connection health.

2. API Health Check

Verify the service is running via the API endpoint:

  • GET http://localhost:8080/api/health
  • Expected Response: {"status": "ok", "timestamp": "..."}

Main Workflows

Workflow 1: Initial Setup

  1. Configure Environment Variables:
    • Set ADO_ORGANIZATION, ADO_PROJECT, and ADO_PAT (Personal Access Token with read/write permissions).
    • Set CLICKUP_API_TOKEN (from ClickUp User Settings > Apps > Private Apps).
    • Set CLICKUP_WORKSPACE_ID.
  2. Start the Service:
    • Run docker-compose up -d.
  3. Verify Connection:
    • Check the Dashboard UI for "Status: OK".
    • Check logs for successful database initialization.

Workflow 2: Synchronizing Tasks

  1. Create an Item in Source System:
    • Create a Task in ClickUp or a Work Item in ADO.
  2. Trigger Sync:
    • Ensure Webhooks are configured in both ADO (Notifications > New Subscription) and ClickUp (Task > Settings > Webhooks).
    • The payload sent to PUBLIC_URL triggers the sync logic.
  3. Verify Sync:
    • Check the Sync Log in the Dashboard.
    • Look for the linked ID in the other system (e.g., "ADO ID: 123" in ClickUp description or custom fields).

Workflow 3: Synchronizing Comments

  1. Add Comment:
    • Post a comment on an ADO Work Item or ClickUp Task.
  2. Automatic Propagation:
    • The webhook triggers the CommentMap logic.
    • The comment appears in the other system.

FAQ

Q: How do I map an ADO Project to a ClickUp Space/List? A: This is handled automatically if CLICKUP_WORKSPACE_ID is correct and the sync runs. You can also use the setup endpoint (/api/setup) to manually bind specific ADO Area Paths to ClickUp Lists.

Q: Which tasks are synced? A: By default, only tasks assigned to the user associated with the ADO_PAT (indicated by @Me). Change ADO_ASSIGNED_TO in .env to sync all tasks or specific users.

Q: What if a sync fails? A: Check the SyncLog table or Dashboard. Common causes include invalid webhooks, network timeouts, or permission issues with the PAT/Token.

Q: Can I undo a sync? A: No, the sync is immediate. Always review changes in the Dashboard log before assuming they are permanent.

Related