Skip to main content

​
Overview

The Gitar YouTrack integration connects a YouTrack instance, InCloud or self-managed, to your pull requests. Gitar reads issues, creates and updates them, comments, and moves them between states.
InCloud and self-managed both work, with one field either way. Enter https://your-company.youtrack.cloud on InCloud.

Read Linked Issues

Resolve a PROJ-123 reference from a PR title, description, or branch name

Validate Against the Issue

Judge a PR against the objectives its issue asks for

Create and Update

Open follow-up issues and update existing ones from a rule

Comment and Transition

Post back to an issue and move it to a new state

​
Before you start

On InCloud there is nothing to check: enter your tenant URL and skip to Connect YouTrack. Self-managed, check your instance against two requirements:
  • HTTPS on port 443 with a publicly trusted certificate. A self-signed certificate does not work.
  • Reachable from Gitar. If you enforce an inbound allowlist, add Gitar’s egress IP addresses.
YouTrack needs no outbound access to Gitar. No webhook is registered, so traffic runs one direction: Gitar reaching your instance on 443. If your instance is served under a context path, enter the whole base URL including it, for example https://tools.your-company.com/youtrack.

​
Connect YouTrack

1

Create a service account

Gitar acts as a dedicated user, so its activity stays attributable and survives staff changes.
  1. Go to Administration → Users → New user
  2. Name it gitar-service
2

Give the account a project role

A YouTrack permanent token carries its user’s own permissions, so what Gitar can reach is decided by this account’s project roles rather than by the token.
  1. Open each project Gitar should work with
  2. Go to Settings → Access and add gitar-service
  3. Give it the Contributor role
Contributor is the role that permits writes: commenting, creating, updating, and transitioning. Use Observer for read-only access.YouTrack renamed these roles in 2026. On an earlier version they are Developer and Reporter.
3

Generate a permanent token

  1. Sign in as gitar-service
  2. Open the profile menu → Profile → Account Security
  3. Under Authentication tokens, click New token and name it gitar
  4. Leave the scope at YouTrack
  5. Copy the token
YouTrack shows the token once. Record its expiry date so you can rotate it before it lapses.
4

Connect YouTrack in Gitar

  1. Go to your organization’s Settings in the Gitar dashboard
  2. Open the Integrations section
  3. Find the YouTrack card under Ticketing & Documentation and click Connect
Enter the two values, then click Connect.

​
Using YouTrack in rules

Ask for YouTrack by name in a custom rule and the agent picks it up. Gitar can look up an issue by id, search, list a project, create, update, comment, and transition. See Rules for how to write one. Search takes YouTrack’s own query language, so a rule can ask for something like #Unresolved Assignee: me and get what the same query returns in the UI. Gitar also reads YouTrack issues for functional validation, which checks a PR against the objectives its issue asks for. That needs no rule.

​
Frequently asked questions

​
Does this work with YouTrack InCloud?

Yes. Enter your tenant URL, for example https://acme.youtrack.cloud, and mint the permanent token the same way, under the service account’s profile. There is no separate API host to enter.

​
Can I give Gitar read-only access?

Yes. Give gitar-service the Observer role instead of Contributor, or Reporter on a pre-2026 instance. Gitar reads issues and every write fails, which is enough for functional validation.

​
Which projects can Gitar see?

Only the projects gitar-service has a role on. A permanent token carries its user’s permissions, so a project role is what limits Gitar. Grant a role on a single project to scope Gitar to it. If the YouTrack card connects but Gitar reports no projects, the account has no role anywhere yet.

​
Can I use YouTrack alongside Jira, Linear, or Plane?

Connect one ticket tracker per organization. A key like PROJ-123 looks identical across all four, so Gitar cannot tell which tracker it belongs to. Jira takes precedence, then Linear, then Plane, then YouTrack. Disconnect the other tracker before connecting YouTrack.

​
Do I need to enable markdown?

No. Gitar writes issue bodies and comments as markdown, which is what current YouTrack renders.

​
What happens when my token expires?

Gitar’s YouTrack calls start failing. Generate a new token in YouTrack, then update it under Settings → Integrations → YouTrack.

​
Why was my base URL rejected?

Gitar accepts HTTPS only, with no exception for a hostname on your internal network. A trailing /api is fine and is trimmed for you.