YouTrack Server 2023.3 Help

Hub Integration

YouTrack is always connected to a Hub service. The Hub service supports authentication, authorization, and user management.

When YouTrack is installed as a self-hosted application, you can choose whether to use the Hub service that is built into YouTrack or install and run Hub as an external application. An external Hub installation lets you centralize user management operations for YouTrack and TeamCity installations. It also enables single sign-on and some additional integration features for these applications.

In a YouTrack Server installation that is integrated with an external Hub service, you have access to a dedicated page in YouTrack that lets you troubleshoot and manage the integration.

Hub integration

To access this page, open the Administration menu and select Server Settings > Global Settings. Scroll to the bottom of the Server Configuration tab and click the Hub Integration > View integration details link.

Deployment Mode

At the top of the Hub Integration page, you see a short description of the Hub service itself. You also see a description of the deployment modes that are available for the Hub integration. The description indicates which mode is currently enabled in YouTrack.

The following example shows a YouTrack Server installation that is connected to an external Hub service:

External Hub integration for YouTrack Server.

When you migrate from the built-in Hub service to an external Hub, you can use this information to verify whether your migration to an external Hub service was successful.

Health Indicators

The Hub Integration page displays a collection of health indicators that you can use to monitor the status of your Hub integration. Use these indicators to diagnose problems with your Hub installation.

Connection to Hub

This indicates whether YouTrack has an active connection to the Hub service. Under normal conditions, the connection status is Active and working.

If your Hub service is down or unresponsive, this metric displays the condition that is the likely source of the problem. Use the following list to resolve the problem:

Status

Description

  • Empty Hub URL

  • Malformed Hub URL

  • Wrong Hub URL

  • YouTrack is not registered in Hub

  • YouTrack is registered in Hub, but its service ID and secret do not match

These messages indicate problems with the installation that require technical support. To ask one of our engineers to repair the Hub integration, submit a support request.

YouTrack isn't trusted in Hub

In most cases, a user has accessed the list of services that are connected to Hub and has distrusted YouTrack. To resolve this problem, access the Services page in Hub and trust the YouTrack service.

Unknown host in Hub URL

The Hub domain name cannot be resolved by your DNS service. Check your network infrastructure or contact your ISP.

Can't connect to Hub

There is a connectivity issue. For details, see Connectivity Issues.

Connection to Hub timed out

Hub is unreachable or has performance issues. For details, see Connectivity Issues.

Hub event sync

This indicator displays the current status of the Hub event sync routine. Under normal conditions, the status is Active, syncing everything.

If the status reads Not started, contact support.

Permission management

Here you see the current source that is used for access authorization. Under normal conditions, the source is Hub permission management. If the status reads YouTrack permission management, contact support.

Hub URL

This is the URL of your Hub service.

If you experience connectivity issues with an external Hub installation, open this URL on the machine that runs YouTrack to verify that the Hub service is accessible from YouTrack.

YouTrack Service ID

Here you find the ID that is assigned to YouTrack as a connected service in Hub.

When a service is connected to Hub, it is assigned a unique service ID. If you want to connect to YouTrack using the REST API, use this service ID for access and authorization.

If you suspect that your Hub integration is not working as intended, follow the instructions for Troubleshooting.

Operations

The Hub Integration page includes a set of tools that you can use to identify and fix problems with the Hub integration. The following operations are available:

Operation

Description

Sync

For improved performance, there are a number of objects that are stored in both the Hub and YouTrack databases. This includes users and their related records for group membership, licenses, notification settings, and so on. These duplicated data structures are mapped using universally unique identifiers (UUIDs).

A background routine regularly checks both sides of the mapping, eliminating possible data discrepancies. If you experience problems with the connection between YouTrack and Hub, the two databases can be out of sync.

This operation synchronizes records for users and groups, using Hub as the data source.

Export

An export routine regularly locates records that only exist in YouTrack and exports them to the Hub database.

This operation locates orphan entities that have not been exported, assigns them UUIDs, and exports them to Hub.

Run diagnostics

This operation conducts a range of self-checks that locate broken mappings, identify suspicious data patterns, and diagnose other problems with the Hub integration. If a problem is located, the diagnostics routine offers a quickfix action, when available. Quickfix actions are found in the Integration Log at the bottom of the page.

There is also a routine diagnostics check that runs in the background. If the background routine detects a problem, you will also see suggestions for available quickfixes in the integration log.

Invalidate caches

Hub provides YouTrack with a remote permission cache. This cache is used to check user permissions in memory without making network calls to Hub.

During Hub outages or similar events, the permission cache may become corrupted. This operation flushes the local permission cache and reloads fresh data from Hub. If you experience unusual behavior related to access permissions in YouTrack, run this operation.

Integration Log

At the bottom of the Hub Integration page, you find a list of recent events that have been written to the integration log.

Hub integration log

Check this section of the page for quickfixes. Use quickfixes to resolve problems that are detected by the diagnostics routine.

Troubleshooting

This section describes the most frequently encountered problems with the Hub integration and the steps you can take to resolve them.

Connectivity Issues

The most obvious indication that there is a problem with your Hub integration is when users are unable to log in. This can mean that YouTrack is unable to establish a connection with the Hub service.

The Connection to Hub metric on the Hub Integration page displays the current connection status. If any of the following status messages are shown, there is a problem with YouTrack that requires the attention of the support team. To resolve any of these issues, submit a support request.

  • Empty Hub URL

  • Malformed Hub URL

  • Wrong Hub URL

  • YouTrack is not registered in Hub

  • YouTrack is registered in Hub, but its service ID and secret do not match

If any of the following conditions are present, follow the instructions provided to investigate and resolve the problem.

Condition — YouTrack cannot establish a connection to the Hub service. The Connection to Hub status reads Can't connect to Hub or Connection to Hub timed out. When you attempt to log in, you see the message Permission management service (Hub) is unavailable.

Cause

Solution

The Hub service has shut down or is unresponsive.

Verify the condition by accessing the Hub service. If you are unable to establish a connection, restart it.

If the problem persists, submit a support request. For faster processing, attach your ring.log and youtrack.log files.

Condition — YouTrack isn't trusted in Hub.

Cause

Solution

In most cases, a user has accessed the list of services that are connected to Hub and has distrusted YouTrack.

Access the Services page in Hub and trust the YouTrack service.

  1. Open the Services menu in the toolbar and select Hub.

  2. In the Server Settings section of the Administration menu, select Services.

  3. Select the YouTrack service on the Services page.

  4. Click the Trust button.

Condition — Unknown host in Hub URL.

Cause

Solution

The Hub domain name cannot be resolved by your DNS service.

Check your network infrastructure or contact your ISP.

Hub Event Sync Issues

Under normal conditions, the Hub event sync status is Active, syncing everything. If any of the following conditions are present, follow the instructions provided to investigate and resolve the problem.

Condition — The Hub event sync status reads Not started.

Cause

Solution

There is a problem with your installation.

Submit a support request.

Condition — The Hub event sync status reads Initialization error or Incompatible Hub server detected.

Cause

Solution

There is either a problem with your installation or the Hub version is incompatible with YouTrack.

Check that you are using the most recent release version. If not, upgrade your installations to the latest versions of YouTrack and Hub.

Permission Management Issues

Under normal conditions, the Permission management status is Hub permission management. If the status displays YouTrack permission management, submit a support request.

Broken Data Mappings

Data mapping is a virtual connection between objects that are stored in the YouTrack and Hub databases. For example, each user has two user profiles. For application features to work properly, these profiles must be linked.

Diagnostic routines check all mappings for consistency and offer quick fixes for any problems they encounter.

Condition — Users report problems with access in one or more projects.

Cause

Solution

There are users who have been added to or removed from groups or other changes that were applied in YouTrack that are not mapped to the Hub database.

  1. Click the Run diagnostics button.

  2. Check the Integration Log at the bottom of the page for errors.

  3. If applicable, apply the quick fixes that are suggested in the Integration Log.

Last modified: 22 March 2024