Add support for Youtrack Issues/Cards

[CanisHelix]

📋 Description

Add support for Issue Counts from JetBrains YouTrack product. Given the customization capabilities of YouTrack on a per project level a standard Open/Closed/All would not suffice. As such the filter would need to be defined as a query to correctly state the YouTrack search criteria. i.e. #Unresolved Type:Bug would be a query getting all open bugs in my project, but someone else could need #Open Type:Issue based on their setup.

Project is the only guarantee, so this could be used in a path routing similar to user/repo that VCS issues badges work.

🔗 Data

An appropriate endpoint is available at: https://www.jetbrains.com/help/youtrack/devportal/resource-api-issuesGetter-count.html

For a private project either self-hosted (depending on the level of security configured) or on their cloud solution, a token would be required.

🎤 Motivation

Many VCS systems now offer an 'External Issues' feature, wherein the Issues don't exist in the VCS like GitHub does, but can exist in a third party external system such as YouTrack. Gitlab/Gitea/Forgejo support this and even translate #123 etc into correct URL's to take them directly into the external issue management tool.

Projects using this feature would not find any benefit of issues badges for the VCS they use, and would not be able to show issues as badges on their websites/readme's.

[chris48s]

OK cool thanks.

Looking at the docs, there don't seem to be any documented rate limits and we haven't had any issues with rate limits on other jetbrains APIs.

In terms of the authentication

https://www.jetbrains.com/help/youtrack/devportal/yt-api-headers.html

seems to say that authorization is needed for all requests. However, it looks like in practice it is actually possible to get some data out about public projects without auth. Is that documented anywhere?

For private or self-hosted projects, how are you envisaging the auth could work? There's some documentation on the constraints in

https://github.com/badges/shields/blob/master/doc/authentication.md

[CanisHelix]

Regarding the headers, I have reached out to their support department who responded with the following:

Without the authorization header, a request is made on behalf of the guest user. This user represents anonymous access, which is enabled in youtrack.jetbrains.com to allow unregistered users to check public issues.

As for private/self-hosted solutions I would envisage the first method of providing a service level token, anyone implementing a badge for this would most likely be an administrator of the project/instance who can set up a service user for this use. A Token can have scopes, but they are application scopes and not read/write privileges etc. Granular permissions would be at an account level rather than a token level. Leading the 2nd option of per user tokens being an unnecessary risk.

If the self-hosted solution enables the guest user and is internet accessible, they would be able to use shields.io without a token and be safe, as guest is unprivileged.

A youtrack_url parameter would be mandatory as there is no canonical public instance of youtrack, but free cloud hosted solutions at _.youtrack.cloud (such an instance would be used for tests also to avoid external factors breaking a test).

[chris48s]

OK. Great that we have confirmation about guest user - thanks 👍

Agree with your thoughts on auth. Auth would be for self hosting users only. Shields.io would be public projects only.

If we want to implement auth for self hosting, we'll also need to implement a YOUTRACK_ORIGINS param. There are some other services where we implement a _ORIGINS param. You can find some examples in https://github.com/badges/shields/blob/master/doc/server-secrets.md there is also some info about why we do this at https://github.com/badges/shields/blob/master/doc/server-secrets.md#authorized-origins

When you say

there is no canonical public instance of youtrack

What is https://youtrack.jetbrains.com/api/ ?

[CanisHelix]

https://youtrack.jetbrains.com/ is the issue tracker that the JetBrains team uses to track its issues across different projects and communicate with its customers.

The publicly available instance is actually only for JetBrains products to share issues with the public. For general users they offer a free cloud service at Cloud Instance or self-hosted options at Server Instnace, both offering a free and paid upgrades depending on users/space etc.

[chris48s]

OK. This all sounds sensible. Happy to review a PR when you get a chance to submit one