YouTrack

YouTrack works the same way on Cloud and self-hosted Server: enter your instance’s base URL (context path included, if any) and a permanent token. Your unresolved assigned issues arrive in the Inbox with their image attachments, and Birch can update the issue’s State field as you pick up work.

Creating the token

Click Create a permanent token in YouTrack ↗ in the connect form. With your base URL filled in, it opens your own instance’s account-security page (<base-url>/users/me?tab=account-security) — in YouTrack, that’s Profile → Account Security, where permanent tokens are minted. With the URL still empty, the link opens JetBrains’ documentation on permanent tokens instead, since there is no shared cloud page to send you to.

The token acts as you: it must be able to read your issues and update their State field.

Adding the account

1. Open Settings → Integrations (⌘, / Ctrl+,) and click the YouTrack tile.

2. Fill the form:

   Field	What to enter
   Base URL	Required. https://your-domain.youtrack.cloud, or your self-hosted YouTrack URL — including any context path, e.g. https://yt.example.com/youtrack
   Permanent token	From Profile → Account Security on your instance

3. Click Verify & connect. Birch verifies the token before storing it; on success the account appears with a Connected badge and Sync now / Remove buttons.

The URL is stored exactly as you typed it — Birch uses one code path for Cloud and Server, so there is no deployment probe and nothing to configure beyond the URL and token. The token lives in the system keychain, and multiple instances can be connected side by side. See the providers overview for the shared connection model.

What you get

• Unresolved assigned issues in the Inbox Tasks tab, synced roughly every 10 minutes — YouTrack’s own “assigned to me, unresolved” query drives the feed, so resolved issues drop out on their own. See the Inbox overview.
• Image attachments as thumbnails. YouTrack descriptions reference images by bare file name, which resolves to nothing outside YouTrack — so Birch takes the issue’s image attachments instead. They appear as thumbnails in the task’s detail pane and are handed to the agent when a workspace launches from the task.
• Hierarchy. Each issue’s parent link is read, and tasks nest under their parent in the Inbox list.
• Issue identifiers like PROJ-123 label the task and its status prompts.

No PRs, no repository matching

YouTrack has no pull requests and no git remote, so clicking Start workspace on a YouTrack task opens the Choose Repository dialog — pick where the work should happen. That’s the designed flow. See Start a workspace from a task.

Status transitions

When you start a workspace from a YouTrack task, or create a PR from that workspace, Birch offers the values of the issue’s State field and sets the one you pick. Two YouTrack-specific details:

• Localized instances work. Birch finds the state field by matching its name against common variants — State, Status, and their localized equivalents — so a Russian-language instance’s «Состояние» field is recognized.
• Remembered statuses carry across projects. Birch remembers your choice by the state’s name. Every YouTrack project has its own state bundle, but the names are shared — so “In Progress” remembered on one project applies cleanly to issues from another.

Configure the behavior per account in Settings → Tasks: Ask each time, Change automatically (after a status has been remembered), or Never offer — see status transitions.

Troubleshooting

• Instance behind a context path won’t connect — include the context path in the base URL (https://host/youtrack). Birch stores and uses the URL verbatim, so what works in your browser is what belongs in the field.
• Status prompt never appears — Birch has to find the issue’s state field by name. Common names and localized equivalents are recognized; a field renamed to something unusual may not be detected, in which case status transitions are simply not offered for that account.
• Issues missing from the Inbox — only unresolved issues assigned to you sync. A resolved issue disappearing from the Tasks tab is the feature working.
• Verification fails — paste the token whole, exactly as YouTrack generated it. Recreate it from Profile → Account Security if in doubt.