YouTrack Guide¶
A hands-on walkthrough of our YouTrack instance at shootify.youtrack.cloud. Covers daily operations, power features, and administration with step-by-step instructions.
Getting access¶
All Sartiq team members get YouTrack accounts. Log in at shootify.youtrack.cloud with your company credentials.
After first login:
- Set your profile photo — helps teammates identify you on boards and assignments
- Check your notification settings — enable email or Slack notifications for assigned issues and mentions
- Browse the four projects (SAR, IDQ, OPS, LAB) to familiarize yourself with the structure
What you should see
The profile settings page shows your avatar upload area, display name, email, and notification preferences. The left sidebar lists sections for General, Notifications, and SSH Public Keys.
Navigating YouTrack¶
Dashboard¶
The dashboard is your landing page. It shows widgets for assigned issues, recent activity, sprint progress, and saved searches.
You can customize your dashboard by adding, removing, or rearranging widgets.
What you should see
The dashboard displays a grid of widgets including "Assigned to Me" (list of your open issues), "Recent Activity" (timeline of updates across projects), a sprint progress donut chart, and any saved search results you have pinned.
Global navigation¶
| Element | Where | What it does |
|---|---|---|
| Project selector | Top nav | Switch between SAR, IDQ, OPS, LAB or view all |
| Search bar | Top nav | Global issue search with query syntax |
| Boards | Left sidebar | Agile boards (sprint and kanban views) |
| Issues | Left sidebar | Full issue list with filters |
| Reports | Left sidebar | Time reports, burndown, issue distribution |
| Agile Boards | Left sidebar | Sprint planning and board management |
What you should see
The top navigation bar contains the project selector dropdown on the left and the global search bar in the center. The left sidebar lists navigation items: Boards, Issues, Reports, and Agile Boards, each with an icon. The currently active section is highlighted.
Switching between projects¶
Use the project selector in the top navigation to switch between SAR, IDQ, OPS, and LAB. You can also view issues across all projects from the global issue list.
What you should see
The project selector dropdown lists four projects: SAR, IDQ, OPS, and LAB, each with its full name and icon. An "All Projects" option appears at the top, and the currently selected project is highlighted with a checkmark.
Creating issues¶
Step by step¶
- Click Create Issue (or press
N) - Select the Project (SAR, IDQ, OPS, LAB)
- Select the Type (Bug, User Story, Task, Epic)
- The description is pre-filled with the template for that type (see Writing Issues)
- Fill in the template sections
- Set Priority, Category, and Tags in the sidebar
- Click Create
What you should see
The new issue dialog shows a Project dropdown, a Type selector (Bug, User Story, Task, Epic), and a Summary field at the top. The description area is pre-filled with the template for the selected type, containing placeholder sections like "## Steps to Reproduce" for bugs or "## Acceptance Criteria" for user stories. The right sidebar displays fields for Priority, Category, Assignee, and Tags.
Setting fields¶
The right sidebar in the issue creation form shows all available fields. See Fields for the full taxonomy.
| Field | When to set |
|---|---|
| Priority | Always — defaults to Normal |
| Category | Usually auto-filled from project default, override if needed |
| Assignee | Set if you know who should do it, otherwise leave for sprint planning |
| Complexity | Set during sprint planning |
| Estimation | Set during sprint planning |
| Tags | Set as many as relevant (backend, frontend, devops, etc.) |
| Sprint | Set during sprint planning |
What you should see
The right sidebar of the issue form displays editable fields stacked vertically: Priority (dropdown, defaults to "Normal"), Category, Assignee (user picker with avatars), Complexity, Estimation, Tags (multi-select chips), and Sprint (dropdown). Each field has a label and a clickable value area.
Attaching files and evidence¶
For bugs and visual issues, attach screenshots or recordings directly:
- Drag and drop images into the description editor
- Attachment button for any file type
- Paste from clipboard with
Ctrl+V— works for screenshots - Link external files using markdown links in the description
What you should see
The issue description area shows an inline image rendered within the markdown body, plus an "Attachments" section below the description listing attached files with thumbnails, file names, and sizes. A drag-and-drop zone with a dashed border appears when hovering files over the editor.
Linking issues¶
Issues can be linked to each other to express relationships:
| Link type | Use case |
|---|---|
| Subtask of | Child issue under an Epic |
| Depends on / Is required for | Blocking dependencies |
| Relates to | Related but independent issues |
| Duplicates | Mark as duplicate of another issue |
To add a link, open an issue and use the Link action in the toolbar, or type parent for SAR-123 in the command bar.
What you should see
The link dialog presents a dropdown to select the link type (Subtask of, Depends on, Relates to, Duplicates) and a search field to find the target issue by ID or keyword. Matching issues appear in an autocomplete list showing their ID, summary, and current state.
Issue detail view¶
Anatomy of an issue¶
When you open an issue, you see:
- Header: issue ID, summary, type icon, state badge
- Description: the main content (template-filled body)
- Sidebar: all fields (state, priority, assignee, tags, sprint, etc.)
- Activity tab: state changes, comments, field updates, linked commits
- Subtasks panel: child issues (for Epics)
What you should see
The issue detail view has four main areas: the header bar with the issue ID (e.g., SAR-42), summary text, type icon, and a colored state badge; the description panel with the rendered markdown body; the right sidebar showing all fields (State, Priority, Assignee, Tags, Sprint, etc.); and tabs at the bottom for Activity and Subtasks.
Commenting¶
Use comments to discuss the issue, ask questions, or provide updates:
- @mention team members to notify them
- Use markdown for formatting (code blocks, lists, links)
- Attach files directly to comments
- Comments support the same command syntax as the command bar — type a command in a comment and it will be applied
What you should see
The comment area shows a text input with a toolbar for markdown formatting (bold, italic, code, link). A submitted comment displays the author's avatar, name, and timestamp, with rendered markdown content including @mentions highlighted as clickable links and code blocks with syntax highlighting.
Time tracking¶
Log time spent on an issue:
- Open the issue
- Click the time tracking widget (or use the command bar:
spent 2h) - Add a work item with duration and optional description
What you should see
The time tracking dialog shows a form with fields for Duration (e.g., "2h 30m"), Date, Work Type (Development, Testing, Documentation), and an optional Description. Below the form, a log of previously recorded work items is listed with their durations, authors, and timestamps.
The issue board¶
Sprint board¶
The sprint board shows all issues in the current sprint, organized by state columns (Open → In Progress → Review → Done).
Each card shows the issue ID, summary, assignee avatar, priority indicator, and tags.
What you should see
The sprint board displays columns for each workflow state: Open, In Progress, Review, and Done. Each column contains issue cards showing the issue ID, summary, assignee avatar, a colored priority indicator on the left edge, and tag chips at the bottom. The sprint name and date range appear in the header above the columns.
Board views¶
YouTrack offers multiple board layouts:
| View | Best for |
|---|---|
| Board | Day-to-day work — drag cards between state columns |
| Backlog | Sprint planning — see unscheduled issues alongside the sprint |
| Timeline | Long-range planning — Gantt-style view of issues over time |
What you should see
The board header contains a view selector with three tabs or buttons: Board (column layout), Backlog (split view with unscheduled issues on the left and the sprint on the right), and Timeline (horizontal Gantt-style bars spanning across calendar dates). The currently active view is highlighted.
Filtering the board¶
Use the board filter bar to narrow down issues:
- By project: show only SAR, or combine IDQ + OPS
- By assignee: your issues only
- By tag: e.g.
backendto focus on backend work - By priority: e.g. Critical and above
Filters can be combined. Your filter selection is saved per session.
What you should see
The filter bar sits above the board columns and shows active filter chips (e.g., "Project: SAR", "Assignee: me", "Tag: backend"). Each chip has an "x" to remove it. A "+" button opens the filter picker to add more criteria. The board below updates to show only issues matching the active filters.
Swimlanes¶
The board can group issues into horizontal swimlanes by any field:
- By assignee: see each person's workload
- By priority: critical issues at the top
- By project: separate SAR, IDQ, OPS, LAB visually
Configure swimlanes from the board settings menu.
What you should see
The board is divided into horizontal swimlanes, one per assignee. Each swimlane header shows the assignee's avatar, name, and issue count. Within each swimlane, issue cards are distributed across the state columns (Open, In Progress, Review, Done), giving a clear view of each person's workload.
Moving issues between states¶
Drag issues between columns to change their state, or click the issue and update the State field directly.
What you should see
When dragging an issue card, it lifts with a slight shadow and follows the cursor. The target column highlights with a colored border or background to indicate where the card will land. Releasing the card in a new column updates the issue's state automatically.
The command bar¶
The command bar is YouTrack's power tool for quick updates. It's faster than clicking through fields one by one.
Opening the command bar¶
- Single issue: open the issue, press
Ctrl+Alt+J - Multiple issues: select issues (checkboxes or
Shift+Click), then pressCtrl+Alt+J - From the board: click the command icon after selecting cards
What you should see
The command bar appears as a text input overlay at the top of the issue view. It has a blinking cursor ready for input, with autocomplete suggestions appearing as you type field names and values. A "Preview" area below the input shows which fields will change and their new values before you apply the command.
Command syntax¶
Commands are space-separated field-value pairs. Multiple commands can be chained in a single entry.
This sets state, assignee, and tag in one action.
Command reference¶
| Command | Syntax | Example |
|---|---|---|
| Set state | state <value> |
state In Progress |
| Set priority | priority <value> |
priority Critical |
| Set type | type <value> |
type Bug |
| Set category | category <value> |
category Infrastructure |
| Set complexity | complexity <value> |
complexity Medium |
| Assign | assignee <login> |
assignee felipe.cardoso |
| Set reviewer | reviewer <login> |
reviewer felipe.cardoso |
| Add tag | tag <name> |
tag backend |
| Remove tag | remove tag <name> |
remove tag frontend |
| Set sprint | sprint <name> |
sprint Customer Shooting Guidelines |
| Set estimation | estimation <period> |
estimation 2d |
| Log time | spent <period> |
spent 3h fixing auth |
| Move to project | project <key> |
project OPS |
| Set parent | parent for <id> |
parent for SAR-100 |
| Add subtask | subtask of <id> |
subtask of SAR-100 |
Bulk operations¶
Select multiple issues first (via checkboxes on the board or issue list), then open the command bar. The command applies to all selected issues.
# Assign all selected to a sprint
sprint Customer Shooting Guidelines
# Reassign and reprioritize
assignee felipe.cardoso priority Major
# Cross-project move with state change
project OPS state Open tag devops
What you should see
Multiple issues are selected with visible checkmarks on each card. A toolbar appears above the list showing the count of selected issues (e.g., "3 issues selected") and action buttons. The command bar is open at the top, ready to accept a command that will be applied to all selected issues simultaneously.
Searching issues¶
Search syntax¶
Use the search bar at the top of any page. YouTrack uses a structured query syntax:
Search operators¶
| Operator | Meaning | Example |
|---|---|---|
: |
Equals | state: Open |
- |
Not | state: -Done |
, |
Or | priority: Critical,Show-stopper |
#{} |
Tag | #{backend} |
has: |
Field is set | has: assignee |
-has: |
Field is not set | -has: assignee |
{...} |
Multi-word value | sprint: {Customer Shooting Guidelines} |
Useful saved queries¶
| Name | Query | What it finds |
|---|---|---|
| My open work | assignee: me state: -Done |
Everything assigned to you |
| My sprint | assignee: me sprint: {Current sprint} |
Your current sprint issues |
| Unassigned bugs | type: Bug state: Open -has: assignee |
Bugs nobody owns |
| Critical+ open | state: -Done priority: Critical,Show-stopper |
Urgent open issues |
| This week's new | created: {this week} project: SAR,IDQ |
Recently created issues |
| Unestimated in sprint | sprint: {Current sprint} -has: estimation |
Sprint issues missing estimates |
| Backend backlog | #{backend} state: Open -has: sprint |
Unscheduled backend work |
Save frequently used queries: run the search, click Save, and name it. Saved searches appear in the sidebar for quick access.
What you should see
The sidebar shows a "Saved Searches" section listing your named queries (e.g., "My open work", "Unassigned bugs", "Critical+ open"). Clicking a saved search immediately populates the search bar with its query and displays the matching issues. A star icon next to each entry lets you pin favorites to the top.
Sprint planning¶
The sprint lifecycle¶
- Create sprint — from the board settings, create a new sprint with a descriptive name
- Fill from backlog — drag issues from the backlog into the sprint
- Estimate — set Estimation and Complexity on each issue
- Run — the sprint is active, work happens
- Close — review completion, carry over unfinished work to the next sprint
Viewing sprint capacity¶
The agile board's sprint view shows:
- Total estimation for the sprint
- Progress per assignee
- Issue count by state
- Carry-over from previous sprint
What you should see
The sprint planning view shows the sprint name, date range, and a summary bar with total estimation (e.g., "24d estimated"), issue count by state, and a per-assignee breakdown listing each team member with their assigned estimation total. Carry-over issues from the previous sprint are marked with a label.
Adding issues to a sprint¶
From the backlog view:
- Open the Backlog panel (unscheduled issues)
- Drag issues into the sprint
- Set Estimation and Complexity for each issue
From the command bar:
What you should see
The backlog view splits the screen: the left panel lists unscheduled issues (the backlog), and the right panel shows the current sprint's columns. Dragging an issue card from the backlog panel into the sprint area moves it into the sprint. A drop-zone highlight appears in the sprint panel to indicate valid placement.
Burndown chart¶
The burndown chart tracks sprint progress over time. Access it from the board's chart icon.
- Ideal line: expected progress if work is evenly distributed
- Actual line: real progress based on issue completion
- Remaining estimation: total hours/days left in the sprint
What you should see
The burndown chart displays a line graph with the sprint timeline on the x-axis and remaining estimation on the y-axis. A straight diagonal "Ideal" line shows expected progress. The "Actual" line plots real completion, typically stepping down as issues are resolved. The gap between the two lines indicates whether the sprint is ahead or behind schedule.
Working with Epics¶
Creating an Epic¶
- Create a new issue with Type = Epic
- Fill in the goal, scope, and success criteria (see Writing Issues — Epic template)
- Add subtasks from the Epic's detail view using Add subtask, or use the command bar on existing issues:
subtask of SAR-100
What you should see
The Epic detail view shows the Epic's summary and description at the top, followed by a "Subtasks" panel listing all child issues. Each subtask row displays its ID, summary, state badge, assignee avatar, and priority. An "Add subtask" button appears at the bottom of the list for creating new child issues directly.
Tracking Epic progress¶
The Epic's detail view shows:
- Subtask count and completion percentage
- Aggregate estimation across all subtasks
- State distribution (how many subtasks are Open, In Progress, Done)
- A progress bar based on completed vs total subtasks
What you should see
The Epic's progress section shows a horizontal progress bar colored by state (e.g., green for Done, blue for In Progress, gray for Open). Above the bar, a summary reads something like "5 of 12 subtasks completed (42%)". Below, a breakdown lists the count of subtasks in each state alongside the aggregate estimation across all subtasks.
Epic on the board¶
Epics appear on the board alongside regular issues. Their card shows a subtask progress indicator. Click to expand and see the subtask list.
Reports¶
Available reports¶
YouTrack includes built-in reports accessible from the Reports section:
| Report | What it shows |
|---|---|
| Time Report | Logged time per user, project, or issue |
| Issue Distribution | Issue count by field (state, priority, type, etc.) |
| State Transition | How issues moved between states over time |
| Burndown | Sprint progress (also available from the board) |
What you should see
The Reports page lists available report types as cards or tiles: Time Report, Issue Distribution, State Transition, and Burndown. Each card has a brief description and a "Create" button. Below the report type selector, previously saved reports appear in a list with their names, date ranges, and a "View" link.
Creating a custom report¶
- Go to Reports in the sidebar
- Click Create Report
- Select the report type
- Configure filters (project, date range, grouping)
- Save for repeated use
Notifications and activity¶
Watching issues¶
Star an issue (click the star icon) to receive notifications on all updates. You're automatically watching:
- Issues assigned to you
- Issues you created
- Issues you commented on
Notification channels¶
Configure where you receive notifications in your profile settings:
- Email — default, all watched updates
- Jabber/XMPP — if configured
- In-app — bell icon in the top navigation
What you should see
The notification settings panel lists event types (Issue assigned to me, Issue I watch is updated, I am @mentioned, etc.) with toggle switches for each notification channel: Email, Jabber/XMPP, and In-app. Each row lets you independently enable or disable notifications for that event on each channel.
Activity stream¶
Each issue has an activity tab showing:
- State changes with timestamps and who made them
- Comments and @mentions
- Field updates (priority changes, reassignments, etc.)
- Linked commits and PRs (via VCS integration)
What you should see
The Activity tab displays a chronological feed of all issue events. Each entry shows a timestamp, the user's avatar and name, and the action taken: state changes appear as "State: Open -> In Progress", field updates show old and new values, comments render inline with markdown formatting, and linked VCS commits display the commit hash and message.
Keyboard shortcuts¶
| Shortcut | Action |
|---|---|
N |
Create new issue |
Ctrl+Alt+J |
Open command bar |
/ |
Focus search bar |
J / K |
Navigate issue list (down / up) |
Enter |
Open selected issue |
O |
Open issue in new tab |
Esc |
Close panel / go back |
Ctrl+Enter |
Submit form (create issue, save comment) |
. |
Toggle issue detail panel |
Markdown reference¶
YouTrack supports Markdown in issue descriptions and comments:
| Syntax | Result |
|---|---|
**bold** |
bold |
*italic* |
italic |
`code` |
inline code |
```lang |
Code block with syntax highlighting |
- [ ] item |
Checkbox (interactive in descriptions) |
[text](url) |
Link |
SAR-123 |
Auto-linked issue reference |
@username |
Mention — notifies the user |
> quote |
Block quote |
 |
Inline image |
Next steps¶
- Writing Issues — templates and standards for each issue type
- Fields — complete field taxonomy reference
- Workflows — issue lifecycle and state machine
- Skills — Claude Code integration for issue management