YouTrack Concepts

This guide explains key YouTrack concepts to help new users understand how to effectively use the YouTrack CLI.

Understanding YouTrack

YouTrack is a comprehensive issue tracking and project management platform developed by JetBrains. It provides powerful tools for tracking bugs, managing features, planning sprints, and coordinating team work.

Core Concepts

Issues

Issues are the fundamental work items in YouTrack. They represent:

  • Bugs - Software defects that need to be fixed

  • Features - New functionality to be implemented

  • Tasks - General work items or to-do items

  • Epics - Large features broken down into smaller issues

Each issue has:

  • ID - Unique identifier (e.g., WEB-123, API-456)

  • Summary - Brief description of the issue

  • Description - Detailed explanation of the issue

  • State - Current status of the issue

  • Priority - Importance level

  • Assignee - Person responsible for the issue

Projects

Projects are containers that organize related issues. Examples:

  • WEB-FRONTEND - Issues related to the web application UI

  • API-BACKEND - Issues for backend API development

  • MOBILE-APP - Mobile application issues

  • INFRA - Infrastructure and DevOps issues

Project IDs are used as prefixes for issue IDs (e.g., issues in WEB-FRONTEND have IDs like WEB-123).

States and Workflow

States represent the current status of an issue in its lifecycle:

Common States: * Open - Issue has been created but work hasn’t started * In Progress - Someone is actively working on the issue * In Review - Work is complete and under review * Resolved - Issue has been fixed/completed * Closed - Issue is finalized and verified * Rejected - Issue was deemed invalid or won’t be fixed

Workflow defines how issues move between states. For example: Open → In Progress → In Review → Resolved → Closed

Priority Levels

Priority indicates how urgent or important an issue is:

  • Critical - System is broken, immediate attention required

  • High - Important issue that should be addressed soon

  • Medium - Normal priority issue

  • Low - Nice-to-have or minor issue

Users and Assignments

Users are people who work with issues:

  • Assignee - Person responsible for working on the issue

  • Reporter - Person who created the issue

  • Watchers - People following the issue for updates

Assignment means giving responsibility for an issue to a specific person.

Tags and Labels

Tags are labels you can attach to issues for organization:

  • urgent - Needs immediate attention

  • bug - Software defect

  • enhancement - Improvement to existing feature

  • documentation - Related to docs

  • frontend, backend - Component-specific tags

Comments and Communication

Comments allow team members to:

  • Ask questions about the issue

  • Provide updates on progress

  • Share solutions or workarounds

  • Discuss implementation approaches

Attachments and Files

Attachments let you add files to issues:

  • Screenshots of bugs

  • Log files for debugging

  • Design mockups for features

  • Documentation or specifications

Issue Relationships

Links connect related issues:

  • depends on - This issue cannot be completed until another is done

  • duplicates - This issue is the same as another issue

  • relates to - This issue is related to another issue

  • blocks - This issue prevents another from being completed

Time Tracking

Time tracking helps monitor work effort:

  • Work time - How long was spent working on the issue

  • Estimates - How long the work is expected to take

  • Time reports - Summary of time spent across issues/projects

CLI Mapping

Here’s how YouTrack concepts map to CLI commands:

Issues Management:

# Create an issue
yt issues create PROJECT-ID "Issue summary" --type Bug --priority High

# List issues in a project
yt issues list --project PROJECT-ID

# Update issue state
yt issues update ISSUE-ID --state "In Progress"

# Assign issue to someone
yt issues assign ISSUE-ID username

Project Operations:

# List all projects
yt projects list

# Create a new project
yt projects create --name "My Project" --key "MP"

Comments and Communication:

# Add a comment
yt issues comments add ISSUE-ID "Comment text"

# List comments
yt issues comments list ISSUE-ID

Time Tracking:

# Log work time
yt time log ISSUE-ID "2h 30m" --description "Fixed the bug"

# Generate time report
yt time report --from "2024-01-01" --to "2024-01-31"

Getting Started Tips

For New YouTrack Users

  1. Start with browsing - Use yt projects list to see available projects

  2. Explore issues - Try yt issues list --project PROJECT-ID to see existing issues

  3. Understand the workflow - Ask your team about the typical issue states

  4. Practice with test issues - Create a few test issues to get comfortable

For CLI Beginners

  1. Use help - Every command has help: yt issues --help

  2. Start simple - Begin with list and search commands before creating

  3. Check twice - Use --dry-run options when available

  4. Learn incrementally - Master basic commands before advanced features

Common Workflows

Daily Developer Workflow:

  1. Check assigned issues: yt issues list --assignee me --state open

  2. Start work: yt issues update ISSUE-ID --state "In Progress"

  3. Add progress comments: yt issues comments add ISSUE-ID "Working on the fix"

  4. Log time: yt time log ISSUE-ID "4h" --description "Implemented solution"

  5. Mark complete: yt issues update ISSUE-ID --state "Resolved"

Bug Triage Workflow:

  1. Search for similar issues: yt issues search "error message".

  2. Create bug report: yt issues create PROJECT "Bug summary" --type Bug

  3. Add details: yt issues comments add ISSUE-ID "Steps to reproduce...".

  4. Set priority: yt issues update ISSUE-ID --priority High

  5. Assign to developer: yt issues assign ISSUE-ID developer-username

Next Steps

Now that you understand YouTrack concepts, you can: