Connect YouTrack
Bring your team's YouTrack issues to the agent with a permanent token and YouTrack's Webhook Triggers app. Approved replies and the agent's findings go back as comments, which a team group can keep to itself.
YouTrack is JetBrains' issue tracker: your team's own list of work. It can be in the cloud, at
an address like https://yourcompany.youtrack.cloud, or on your own server. Connect it, and new
issues in the projects you choose reach the agent. Approved replies go back as comments on the
issue. So can the agent's findings, if you want them.
Who sees the comments
A YouTrack comment is seen by everyone who can see the issue, including the person who reported it. Choose a team group to keep the agent's findings to your team. With a team group, you can also send approved replies as notes only that group sees.
A platform has one ticket system at a time. If this platform uses another one, disconnect it first. See Connect your ticket system.
Before you start#
- A YouTrack user for the token. Comments we add show as written by the user whose token it is. Best: a user used only for this, such as one named "Cerberius Agent". It must be able to see and comment on the platform's projects. Comments by that user never count as replies from the person who reported an issue.
- A YouTrack admin, to add the Webhook Triggers app and set it up in each project. The app tells us when an issue changes. Adding it needs the Low-level Admin Write permission, and setting it up in a project needs Update Project.
Connect YouTrack#
- 1
In YouTrack, sign in as the user the comments should come from. Click your avatar and choose Profile. Open the Account Security tab and click New token. Give it a name, choose the YouTrack scope, and click Create token. Copy the token. It starts with
perm:, and YouTrack shows it only once. Show me how on our page shows these steps too. - 2
Here, go to Settings › Ticket system. On the Connection tab, click Connect a ticket system and choose YouTrack.
- 3
Under Your YouTrack, type the Address you open YouTrack at, and paste the token into Permanent token.
- 4
Under Which issues, click Show my projects. Tick the projects whose issues come to this platform.
- 5
Optional: under Team group, choose your team's YouTrack group.
- 6
Under Approved replies, choose A comment on the issue or A note for your team. Under Agent's findings in YouTrack, turn the findings on or off.
- 7
Click Connect YouTrack. Then click Check connection.
- 8
In YouTrack, a YouTrack admin goes to Administration › Apps. If Webhook Triggers isn't listed, they add it from the From Marketplace tab. They open Webhook Triggers, and on its Projects tab click Manage projects, choose the projects you ticked, and click Save.
- 9
Then, for each of those projects, they go to Projects, open the project, and choose Settings › Apps › Webhook Triggers, then its Settings tab. They paste the Webhook token from Let YouTrack tell us about new issues on our page as the webhook token, and leave the header name as
X-YouTrack-Token. They paste the Webhook address into All events, at the bottom, and save. - 10
Try it. Create a test issue in one of those projects. It shows under Tickets here within a minute, and our page says Last heard from YouTrack with the time.
Every project uses the same Webhook address and Webhook token. Issues of projects you didn't tick are read and then left out.
YouTrack keeps one webhook token per project. If the Webhook Triggers app in your projects already has a token for another service, paste that token into Use a token you already have on our page, and click Save. We then expect it instead of ours.
Settings#
| Setting | What it does |
|---|---|
| Address | Where YouTrack is. It must start with https://. You can paste the address of any YouTrack page: we keep only the part before it. |
| Permanent token | The token we read issues and add comments with. We try a new token with YouTrack before saving it, and a token YouTrack refuses is not saved. Once saved, it is never shown again. Paste a new one to replace it. To change the Address, paste the token again: the saved token is only ever sent to the address it was saved for. |
| Token user | Shows once YouTrack is connected: the user comments show as written by. |
| Check connection | Shows once YouTrack is connected. It asks YouTrack who the token belongs to, and says whether that worked. |
| Which issues | The projects whose issues come to this platform: the projects whose systems this platform can look into. Tick at least one. A project that another of your platforms takes can't be ticked, and says which platform takes it. Two platforms never take the same project. Archived projects aren't listed. |
| Webhook address | Shows once YouTrack is connected. Paste it into the Webhook Triggers app, with Copy. Keep it private. We only ever read the issue with your token, and take only your chosen projects' issues. |
| Webhook token | Shows once YouTrack is connected, to people who may change settings. Paste it into the Webhook Triggers app. A call to the webhook address without it is refused. Make a new secret makes another one: the old one stops at once, so paste the new one into every project's Webhook Triggers settings straight away. |
| Last heard from YouTrack | When YouTrack last called the webhook address. Never yet means it hasn't called: check the steps. If a call was refused, it says when and why, such as wrong secret. |
| Use a token you already have | Optional. Only if your projects' Webhook Triggers app already has a token for another service. At least 32 characters. |
| Team group | Optional. A YouTrack group, such as your support team. With one chosen, the agent's findings are comments only its members see. Groups that hold every user aren't offered. |
| Approved replies | A comment on the issue: everyone who can see the issue sees it, its reporter too. A note for your team: a comment only the team group sees. Your team then answers the reporter themselves. Needs a team group. |
| Agent's findings in YouTrack | When on, a comment with what the agent found and what it proposes goes on the issue as soon as a reply is ready to approve. Only the team group sees it if you chose one. Otherwise everyone who can see the issue does. Off at first. |
| Who sees our comments | Says, in plain words, who sees replies and findings with the choices you made. |
Once YouTrack is connected, change anything here and click Save at the bottom.
What happens with an issue#
- A new issue in a ticked project reaches the agent with the files attached to it. The person who reported it in YouTrack is the requester. What they added in comments before it reached us is part of the request.
- A comment by the reporter reaches the agent as a follow-up, with its files. Files the reporter attached to the issue itself since come with their next comment. Comments by anyone else, and by the token's user, are skipped.
- Resolving it in YouTrack stops the work here. An issue is resolved when its State is one YouTrack counts as resolved, such as Fixed.
- An approved reply becomes a comment on the issue, or a note only the team group sees. Nothing else on the issue changes.
- Closing it here sets the issue's State to Fixed, or Done if the project has no Fixed, or else the first resolved state of the project. An issue resolved in YouTrack already stays as it is.
- An issue moved to another project keeps coming here, under its new ID.
Closing it here doesn't work, and says so on the ticket, when:
- a workflow controls the project's State field (a state machine), or doesn't allow the change;
- the project has no resolved state.
Close the issue in YouTrack then.
Some issues don't come in:
- Issues opened before you connected YouTrack. YouTrack tells us about every change to every issue in the projects, and older work someone edits is not new work for the agent.
- Issues already resolved when YouTrack first tells us about them.
- Issues of projects you didn't tick.
The ticket page shows the issue as YouTrack has it now: its ID, State, assignee, priority, project and Due Date, with Open in YouTrack.
Only tickets that came from YouTrack go back to YouTrack. Other tickets on the same platform, from the log watcher for example, don't.
Stop#
Click Disconnect… at the top of the Connection tab, and confirm. New issues from YouTrack stop coming in, and replies stop going back to it. The webhook address stops working at once. Tickets already here stay. To be tidy, remove the webhook address from the Webhook Triggers app in YouTrack, and delete the token on the Account Security tab of the token user's profile.