> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTrack

> Connect a YouTrack instance so Gitar can read and update issues

## Overview

The Gitar YouTrack integration connects a [YouTrack](https://www.jetbrains.com/youtrack/) instance, InCloud or self-managed, to your pull requests. Gitar reads issues, creates and updates them, comments, and moves them between states.

<Note>
  InCloud and self-managed both work, with one field either way. Enter `https://your-company.youtrack.cloud` on InCloud.
</Note>

<CardGroup cols={2}>
  <Card title="Read Linked Issues" icon="link">
    Resolve a `PROJ-123` reference from a PR title, description, or branch name
  </Card>

  <Card title="Validate Against the Issue" icon="list-check">
    Judge a PR against the objectives its issue asks for
  </Card>

  <Card title="Create and Update" icon="plus-circle">
    Open follow-up issues and update existing ones from a rule
  </Card>

  <Card title="Comment and Transition" icon="message-square">
    Post back to an issue and move it to a new state
  </Card>
</CardGroup>

## Before you start

On InCloud there is nothing to check: enter your tenant URL and skip to [Connect YouTrack](#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

<Steps>
  <Step title="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`
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.

    | Field             | Value                                                 | Example                       |
    | ----------------- | ----------------------------------------------------- | ----------------------------- |
    | YouTrack Base URL | Your instance, HTTPS only, including any context path | `https://acme.youtrack.cloud` |
    | Permanent Token   | The token you copied earlier                          | `perm-...`                    |
  </Step>
</Steps>

## 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](/features/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](/features/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.