YouTrack Cloud and Server setup

Before connecting YouTrack

Use this page when the customer wants WebRiskOps to create or update YouTrack issues for report findings or fix tasks. YouTrack setup must separate YouTrack Cloud from YouTrack Server before WebRiskOps asks for project, issue type, tags, users or custom field mapping. Start from `/settings` after Cloud and self-hosted integrations confirms the deployment mode. Do not save a YouTrack token until the customer-owned site, project, auth method and network path are clear.

Connect a YouTrack target

Follow the path `Cloud and self-hosted integrations → YouTrack target → Project and custom field check → Work management export or fallback`.

1. Open /settings and review Integration status, then choose YouTrack Cloud or YouTrack Server setup. Result: provider_key is recorded as youtrack_cloud or youtrack_server before project fields are requested.
2. For YouTrack Cloud, confirm the customer-owned youtrack.cloud site URL and choose the supported token auth_method. Result: credentials are limited to the cloud site that will receive issues.
3. For YouTrack Server, enter base_url only after the customer confirms ownership, reachable REST API and scan or export authorization. Result: deployment_mode is self-hosted and private-network checks run before tokens are accepted.
4. Select project_id for the issue destination. Result: WebRiskOps can discover YouTrack issue fields, tags and users for the selected project.
5. Confirm scopes for issues, projects, custom fields, tags and users. Result: WebRiskOps can validate issue_type, tags, assignee and priority mapping without asking for unrelated YouTrack administration access.
6. Review allowlist_status for YouTrack Server. Result: firewall, VPN or approved tunnel state is visible before WebRiskOps tries provider API calls.
7. Save only when provider auth, project mapping and network checks are ready. Result: the YouTrack target is available to work management export without exposing secrets in documentation or support messages.
8. If PROVIDER_AUTH_REQUIRED appears, reconnect the YouTrack token before retrying. Result: the target stays blocked until valid credentials exist.
9. If PROVIDER_BASE_URL_BLOCKED or PROVIDER_SCOPE_UNAVAILABLE appears, fix the URL or scope, or use portable fallback. Result: unsafe server URLs and unavailable YouTrack permissions do not receive evidence.
10. Continue to Work management export after setup. Result: project_id, issue_type, tags, assignee and priority mapping use the same YouTrack provider record.

Configure YouTrack authorization

YouTrack setup should collect only the access needed for the customer's export path.

• `youtrack_cloud` is for JetBrains-hosted YouTrack Cloud sites ending in `youtrack.cloud`.
• `youtrack_server` is for customer-owned YouTrack Server hosts that need a `base_url`, explicit authorization and network checks.
• `auth_method` should identify permanent token or provider-supported token setup before a credential is saved.
• `scopes` should allow issue create/update plus project, custom field, tag and user lookup, but not unrelated administration.
• `allowlist_status` should be clear before WebRiskOps retries self-hosted YouTrack Server API calls.
• Revoke the token in YouTrack first, then disconnect the YouTrack target in WebRiskOps so historical issues keep references without keeping live credentials.

Ready YouTrack integration states

Continue only when the destination project and custom field mapping can safely receive export work.

• YouTrack Cloud ready means `provider_key` is `youtrack_cloud`, the cloud site belongs to the customer and credentials are active.
• YouTrack Server ready means `provider_key` is `youtrack_server`, `deployment_mode` is self-hosted and `base_url` passed URL safety checks.
• Project ready means `project_id` identifies the customer-owned YouTrack project.
• Field mapping ready means issue_type, custom_fields, tags, assignee and priority mapping match the project workflow.
• Network ready means `allowlist_status` shows the Server target is reachable through a safe direct, allowlisted or customer-approved tunnel path.

Blocked YouTrack setup states

Blocked YouTrack setup should explain exactly what the customer can fix next.

• `PROVIDER_AUTH_REQUIRED` means reconnect the YouTrack token before saving or retrying export.
• `PROVIDER_BASE_URL_BLOCKED` means the YouTrack Server URL failed ownership, redirect, DNS, reserved-IP or private-network checks.
• `PROVIDER_SCOPE_UNAVAILABLE` means the saved token cannot read project metadata, create issues or update existing issues.
• Missing `project_id` means work management export cannot place the issue.
• Missing issue_type, required custom fields, workflow rules, tags or project permissions can still block export after setup; those are handled on the Work management export page.

Continue after YouTrack setup

Continue to Work management export when the target is active and mapped to the customer project. Use Status sync and duplicate handling when a YouTrack issue already exists, Portable export fallbacks when YouTrack cannot be made safe, Azure DevOps Services and Server setup when the team tracks remediation in Azure DevOps, or Asana setup when the team uses Asana.