93 lines
No EOL
3.8 KiB
Markdown
93 lines
No EOL
3.8 KiB
Markdown
---
|
|
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]] |