feat(youtrack): add config-ui plugin — connection form, scope picker, transformation widget

Author: Evgenii Davydov

config-ui/src/api/plugin/index.ts

@@ -21,6 +21,7 @@ import { request } from '@/utils';
 import * as jira from './jira';
 import * as tapd from './tapd';
 import * as webhook from './webhook';
+import * as youtrack from './youtrack';
 
 export const list = (): Promise<[{ plugin: string }]> => request('/plugins');
 
@@ -29,6 +30,7 @@ export const plugin = {
   jira,
   tapd,
   webhook,
+  youtrack,
 };
 
 export default plugin;

config-ui/src/api/plugin/youtrack/index.ts

@@ -0,0 +1,77 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { request } from '@/utils';
+
+export type YoutrackBundleValue = {
+  id: string;
+  name: string;
+  isResolved?: boolean;
+  ordinal?: number;
+  archived?: boolean;
+};
+
+// YoutrackProjectCustomField mirrors one entry of the
+// /admin/projects/{id}/customFields response as requested by the widget's
+// fields param. `project(shortName)` rides along so the union tables can
+// badge projects by the issue-key prefix users recognize (PROJ in PROJ-123).
+export type YoutrackProjectCustomField = {
+  id: string;
+  $type: string;
+  field?: {
+    id: string;
+    name: string;
+    fieldType?: {
+      id: string;
+      valueType: string;
+      isMultiValue: boolean;
+    };
+  };
+  bundle?: {
+    id: string;
+    values?: YoutrackBundleValue[];
+  } | null;
+  project?: {
+    shortName: string;
+  } | null;
+};
+
+export type YoutrackScopeConfigProjects = {
+  count: number;
+  projects?: Array<{
+    name: string;
+    blueprintId: ID;
+    scopes?: Array<{
+      scopeId: string;
+      scopeName: string;
+    }>;
+  }>;
+};
+
+export const customFields = (prefix: string, projectId: string): Promise<YoutrackProjectCustomField[]> =>
+  request(`${prefix}/admin/projects/${projectId}/customFields`, {
+    data: {
+      fields:
+        'id,$type,field(id,name,fieldType(id,valueType,isMultiValue)),bundle(id,values(id,name,isResolved,ordinal,archived)),project(shortName)',
+    },
+  });
+
+// scopeConfigProjects is the singular, un-nested route (Linear's asymmetry):
+// it deliberately takes no connectionId.
+export const scopeConfigProjects = (scopeConfigId: ID): Promise<YoutrackScopeConfigProjects> =>
+  request(`/plugins/youtrack/scope-config/${scopeConfigId}/projects`);

config-ui/src/plugins/components/connection-form/index.tsx

@@ -18,7 +18,7 @@
 
 import { useState, useEffect, useMemo } from 'react';
 import { isEqual, pick } from 'lodash';
-import { Flex, Alert, Button } from 'antd';
+import { Flex, Alert, Button, message } from 'antd';
 
 import API from '@/api';
 import { useAppDispatch, useAppSelector } from '@/hooks';
@@ -131,7 +131,7 @@ export const ConnectionForm = ({ plugin, connectionId, onSuccess }: Props) => {
 
   const handleTest = async () => {
     const isUpdate = type === 'update' && !!connectionId;
-    await operator(
+    const [success, res] = await operator(
       () =>
         isUpdate
           ? API.connection.test(
@@ -143,8 +143,13 @@ export const ConnectionForm = ({ plugin, connectionId, onSuccess }: Props) => {
       {
         setOperating,
         formatMessage: () => 'Test Connection Successfully.',
+        hideToast: !!pluginConfig.connection.showTestResultMessage,
       },
     );
+
+    if (success && pluginConfig.connection.showTestResultMessage) {
+      message.success(res?.message || 'Test Connection Successfully.');
+    }
   };
 
   const handleSave = async () => {

config-ui/src/plugins/components/scope-config-form/index.tsx

@@ -38,6 +38,7 @@ import { ArgoCDTransformation } from '@/plugins/register/argocd';
 import { GhCopilotTransformation } from '@/plugins/register/gh-copilot';
 import { AsanaTransformation } from '@/plugins/register/asana';
 import { ClickUpTransformation } from '@/plugins/register/clickup';
+import { YoutrackTransformation } from '@/plugins/register/youtrack';
 import { DOC_URL } from '@/release';
 import { operator } from '@/utils';
 
@@ -326,6 +327,16 @@ export const ScopeConfigForm = ({
                   setTransformation={setTransformation}
                 />
               )}
+
+              {plugin === 'youtrack' && (
+                <YoutrackTransformation
+                  entities={entities}
+                  connectionId={connectionId}
+                  scopeConfigId={scopeConfigId}
+                  transformation={transformation}
+                  setTransformation={setTransformation}
+                />
+              )}
             </Form>
           </Card>
           <Flex justify="flex-end" gap="small">

config-ui/src/plugins/register/index.ts

@@ -41,6 +41,7 @@ import { RootlyConfig } from './rootly';
 import { SonarQubeConfig } from './sonarqube';
 import { TAPDConfig } from './tapd';
 import { WebhookConfig } from './webhook';
+import { YoutrackConfig } from './youtrack';
 import { ZenTaoConfig } from './zentao';
 import { OpsgenieConfig } from './opsgenie';
 import { TeambitionConfig } from './teambition';
@@ -77,6 +78,7 @@ export const pluginConfigs: IPluginConfig[] = [
   TestmoConfig,
   ZenTaoConfig,
   WebhookConfig,
+  YoutrackConfig,
   OpsgenieConfig,
   TeambitionConfig,
 ].sort((a, b) => a.sort - b.sort);

config-ui/src/plugins/register/youtrack/assets/icon.svg

@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { IPluginConfig } from '@/types';
+
+import Icon from './assets/icon.svg?react';
+import { Endpoint } from './connection-fields';
+
+export const YoutrackConfig: IPluginConfig = {
+  plugin: 'youtrack',
+  name: 'YouTrack',
+  icon: ({ color }) => <Icon fill={color} />,
+  sort: 21,
+  connection: {
+    docLink: 'https://www.jetbrains.com/help/youtrack/devportal/youtrack-rest-api.html',
+    initialValues: {},
+    // the test API's diagnostics are the point of the test button: the
+    // success message names the token's login (and warns on a non-perm:
+    // token); failures (guest fallback, missing /youtrack prefix) already
+    // surface through the error toast
+    showTestResultMessage: true,
+    fields: [
+      'name',
+      ({ type, initialValues, values, errors, setValues, setErrors }: any) => (
+        <Endpoint
+          key="endpoint"
+          type={type}
+          initialValues={initialValues}
+          values={values}
+          errors={errors}
+          setValues={setValues}
+          setErrors={setErrors}
+        />
+      ),
+      {
+        key: 'token',
+        label: 'Permanent Token',
+        subLabel:
+          'Your YouTrack permanent token — it starts with `perm:` (YouTrack → Profile → Account Security → New Token). The Test button detects a token that silently authenticated as guest.',
+      },
+      'proxy',
+      {
+        key: 'rateLimitPerHour',
+        subLabel: 'Maximum number of API requests per hour. Leave blank for the default (10000).',
+        defaultValue: 10000,
+      },
+    ],
+  },
+  dataScope: {
+    // the backend serves remote-scopes only (no search-remote-scopes), so
+    // search is client-side over the loaded projects (jenkins pattern)
+    localSearch: true,
+    title: 'Projects',
+  },
+  scopeConfig: {
+    entities: ['TICKET', 'CROSS'],
+    transformation: {
+      typeField: '',
+      stateField: '',
+      priorityField: '',
+      assigneeField: '',
+      storyPointField: '',
+      dueDateField: '',
+      typeMappings: {},
+      statusMappings: {},
+    },
+  },
+};

config-ui/src/plugins/register/youtrack/config.tsx

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { validateEndpoint } from './endpoint';
+
+describe('validateEndpoint', () => {
+  it('accepts the InCloud shape with the /youtrack context path', () => {
+    expect(validateEndpoint('https://example.myjetbrains.com/youtrack/api')).toBe('');
+  });
+
+  it('accepts the youtrack.cloud shape', () => {
+    expect(validateEndpoint('https://example.youtrack.cloud/api')).toBe('');
+  });
+
+  it('accepts self-hosted shapes, with and without a context path', () => {
+    expect(validateEndpoint('https://youtrack.example.com/api')).toBe('');
+    expect(validateEndpoint('https://www.example.com/youtrack/api')).toBe('');
+  });
+
+  it('accepts http for self-hosted', () => {
+    expect(validateEndpoint('http://youtrack.internal:8080/api')).toBe('');
+  });
+
+  it('accepts a trailing slash (normalized like the backend)', () => {
+    expect(validateEndpoint('https://example.myjetbrains.com/youtrack/api/')).toBe('');
+    expect(validateEndpoint('https://example.myjetbrains.com/youtrack/api//')).toBe('');
+  });
+
+  it('rejects an empty endpoint as required', () => {
+    expect(validateEndpoint('')).toBe('endpoint is required');
+  });
+
+  it('rejects a URL that does not end in /api, with the example in the message', () => {
+    const message = validateEndpoint('https://example.myjetbrains.com/youtrack');
+    expect(message).toContain('/api');
+    expect(message).toContain('https://example.myjetbrains.com/youtrack/api');
+  });
+
+  it('rejects the most common InCloud error — the missing /youtrack prefix surfaces as a non-/api path', () => {
+    expect(validateEndpoint('https://example.myjetbrains.com')).not.toBe('');
+  });
+
+  it('rejects non-absolute URLs', () => {
+    expect(validateEndpoint('example.myjetbrains.com/youtrack/api')).not.toBe('');
+    expect(validateEndpoint('/youtrack/api')).not.toBe('');
+  });
+
+  it('rejects non-http(s) schemes', () => {
+    expect(validateEndpoint('ftp://example.com/api')).not.toBe('');
+  });
+});