---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: User_Manual
status: active
tags:
- domain/devops
- status/active
- tech/azure-ad
- tech/docker
- tech/fastapi
- type/sop
type: 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
- [[01 Projects/DevOps_Click_UP_sync/DEVELOPER_MANUAL]]
- [[01 Projects/DevOps_Click_UP_sync/DEVELOPER_MANUAL.md]]
- [[01 Projects/DevOps_Click_UP_sync/USER_MANUAL.md]]