From 3a5d93a78b8d04ebb423d35c882c25acf0d79c41 Mon Sep 17 00:00:00 2001
From: Klesh Wong <klesh@qq.com>
Date: Mon, 2 Nov 2026 14:39:16 +0800
Subject: [PATCH] docs: add the YouTrack plugin

YouTrack was added to devlake in apache/devlake#9169 and ships with
v1.0.3-beta19, but the site has no page for it and the supported data
sources table does not mention it.

Covers what the plugin collects, the perm: token requirement, the
custom-field mapping in the scope config, and the API form of the
connection for advanced-mode users.
---
 docs/Overview/SupportedDataSources.md |  1 +
 docs/Plugins/youtrack.md              | 48 +++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 docs/Plugins/youtrack.md

diff --git a/docs/Overview/SupportedDataSources.md b/docs/Overview/SupportedDataSources.md
index d8d09d8c846..2728d41ffbe 100644
--- a/docs/Overview/SupportedDataSources.md
+++ b/docs/Overview/SupportedDataSources.md
@@ -15,6 +15,7 @@ more plugins. Detailed plugin docs can be found [here](/docs/Plugins).
 | GitHub              | Source Code Management, Code Review, Issue Tracking, CI/CD (GitHub Actions) | Cloud                              | Available               | `github`, `gitextractor`      | Incremental Sync                                                    |
 | GitLab              | Source Code Management, Code Review, Issue Tracking, CI/CD (GitLab CI)      | Cloud, Community Edition 11+       | Available               | `gitlab`, `gitextractor`      | Full Refresh, Incremental Sync(for `issues`,`MRs`)                  |
 | Jira                | Issue Tracking                                                              | Cloud, Server/Data Center 7.x and above  | Available               | `jira`                        | Full Refresh, Incremental Sync(for `issues` and related)            |
+| YouTrack            | Issue Tracking                                                              | Cloud, self-hosted (configurable endpoint) | Available             | `youtrack`                    | Full Refresh, Incremental Sync(for `issues`, `comments`, `changelogs`) |
 | Jenkins             | CI/CD                                                                       | 2.263.x+                           | Available               | `jenkins`                     | Incremental Sync                                                    |
 | BitBucket (Beta)    | Source Code Management, Code Review                                         | Cloud                              | Advanced Mode Available | `bitbucket`, `gitextractor`   | Full Refresh                                                        |
 | TAPD (Beta)         | Issue Tracking                                                              | Cloud                              | Advanced Mode Available | `tapd`                        | Full Refresh, Incremental Sync(for `stories`, `bugs`, `tasks`)      |
diff --git a/docs/Plugins/youtrack.md b/docs/Plugins/youtrack.md
new file mode 100644
index 00000000000..6116887bfb2
--- /dev/null
+++ b/docs/Plugins/youtrack.md
@@ -0,0 +1,48 @@
+---
+title: "YouTrack"
+description: >
+  YouTrack Plugin
+---
+
+## Summary
+
+This plugin collects `YouTrack` projects, issues, comments, issue changelogs, labels and accounts, and converts them into DevLake's TICKET domain layer so they can be used by the issue-tracking metrics and dashboards.
+
+Issues, comments and changelogs are collected incrementally, so a scheduled pipeline only pulls what changed since the last run.
+
+## Supported Versions
+
+Available for YouTrack Cloud, and for self-hosted YouTrack instances through the configurable endpoint. Check [this doc](https://devlake.apache.org/docs/Overview/SupportedDataSources#data-sources-and-data-plugins) for more details.
+
+## Configuration
+
+The connection needs three things:
+
+| Field | Description |
+|---|---|
+| Endpoint | Base URL of the instance, for example `https://example.youtrack.cloud` |
+| Token | A permanent token. It starts with `perm:` — create one under **Profile → Account Security → New Token** |
+| Rate Limit Per Hour | Optional throttle for the API |
+
+The token must be able to read the project and its custom fields. A token that silently authenticates as a guest returns empty results rather than an error, which is why the Config UI **Test connection** button warns when that happens.
+
+After the connection is saved, pick the projects to collect as scopes, then map the project's custom fields to DevLake's Type, State, Priority, Assignee, Story Points and Due Date in the scope config. Type, State, Priority and Assignee fall back to YouTrack's default field names when left empty.
+
+## Configuration via API
+
+A connection can also be created directly:
+
+```
+curl 'http://localhost:8080/plugins/youtrack/connections' \
+--header 'Content-Type: application/json' \
+--data-raw '
+{
+    "name": "youtrack",
+    "endpoint": "https://example.youtrack.cloud",
+    "token": "perm:<YOUR_TOKEN>",
+    "rateLimitPerHour": 10000
+}
+'
+```
+
+See [Advanced mode](/Configuration/AdvancedMode.md) for collecting scopes and scope configs the same way.