How it works
The YouTrack connector indexes issues and their comments. Each issue carries its project, its public custom fields (state, priority, assignee and so on) and, once resolved, its resolution time as metadata. The reporter is recorded as the issue’s owner. Onyx checks YouTrack for new and changed issues every 30 minutes.
The connector supports YouTrack Cloud and YouTrack Server. Sync with YouTrack needs YouTrack 2026.1 or later.
Setting up
Authorization
The connector signs in with a permanent token. Onyx sees exactly what the token’s user sees, so give that user Read Issue and Read Issue Comment in every project you want to index. For Sync with YouTrack, see Sync with YouTrack for the extra permissions the token’s user needs.1
Open your YouTrack profile
In YouTrack, select your avatar and open your profile, then open the Account Security tab.
2
Create a permanent token
Under Tokens, select New token…. Give the token a name, keep the YouTrack scope selected,
and select Create.
3
Copy the token
Copy the token now. YouTrack shows it only once.
Indexing
1
Open YouTrack connector
In the Onyx UI, navigate to the Admin Panel and select the YouTrack Connector
2
Enter the YouTrack URL
Enter your YouTrack address, for example
https://example.youtrack.cloud. For YouTrack Server,
include the context path, for example https://example.com/youtrack.3
Connect a YouTrack account
Select New YouTrack Account and paste the permanent token. The token is saved with the connector.
4
Choose what to index
Leave Projects empty to index every project the token’s user can read. To narrow the index,
enter project short names, for example
ABC.Onyx checks every entry before you create the connector and names any project YouTrack does not answer for.
That means the short name is wrong, or the token’s user has no access to the project.5
Choose who can see the issues
- Everyone in Your Organization makes every indexed issue visible to every Onyx user.
- Specific Groups limits the connector to selected Onyx groups.
- Sync with YouTrack mirrors YouTrack’s own access and is available on Onyx Cloud and Enterprise Edition.
6
Review the connection checks
Once an account is selected, Onyx runs its checks against YouTrack and lists each one in the form.
Create Connector is enabled once the required checks pass. A failed check names what to fix.
7
Create connector
Click
Create Connector to begin indexing YouTrack issues and comments!Connection checks
Each check reads from YouTrack with the token, so a failure points at the token user’s access.
The token and issues checks run for every connector, and the projects check whenever short names are entered.
The rest run only with Sync with YouTrack, and run again before each scheduled permission sync,
so a token that loses access stops the sync instead of hiding issues.
If no issue in scope exists yet, the issues check passes with a note that comment access was not checked.
Sync with YouTrack
With Sync with YouTrack, an Onyx user finds an issue only if their YouTrack account, matched by email, can see it:- An issue is visible to everyone who holds both Read Issue and Read Issue Comment in its project, whether through a project, organization or global role, a group, or the project team.
- An issue with a Visible to restriction is visible only to the listed users and groups who also hold those permissions in the project, plus the reporter and the holders of Override Visibility Restrictions among them.
- In a helpdesk project, a ticket is visible to the users and groups its visibility names and to its reporter, with no project role required. Customer accounts never see tickets through project roles.
- Banned users see nothing. Issues are never made visible to every Onyx user, since YouTrack issues are never readable without signing in.