Issues & Boards

Track work with list view, Kanban boards, and powerful filters.

Creating Issues

Velocity offers multiple ways to create issues:

  • Inline creator — press C to add an issue directly in the list. Type a title and press Enter.
  • + New Issue button — click in the toolbar for quick creation with just a title.
  • AI Create — click the AI button (sparkle icon) in the toolbar to describe an issue in natural language. AI extracts the title, description, priority, team, labels, and project for you to review before creating. Requires the Business plan. See Smart Issue Creation.

Screenshots and attached files

When creating an issue, choose Add description / images. In a new or existing description, paste a screenshot with Cmd+V or Ctrl+V, or use Attach image to select multiple local files. PNG, JPEG and WebP images up to 4 MiB each are supported. Upload placeholders keep their order while you continue writing.

Finish, retry or remove unfinished uploads before saving. A failed upload or save keeps your text available for correction. Saved images remain visible after reopening or refreshing. Use the full-size link to inspect an image and Remove image to remove it from the description.

Attachments are private to authorized workspace members. Each issue supports 50 files; cancelled drafts expire after 24 hours, and deleted images or issues queue file cleanup. Files uploaded through the management CLI appear under Attached files. Other file types download as binary rather than opening as web content.

List View

The default view shows issues in a flat list, sorted by priority and creation date. Each row displays the issue identifier, status icon, title, priority, assignee, and labels. Click any issue to open the detail panel.

Kanban Board

Toggle to board view with the view switcher in the toolbar. Issues are grouped into columns by status. Drag and drop to move issues between statuses or reorder within a column.

Reordering uses fractional indexing so changes are fast and conflict-free even when multiple people drag simultaneously.

Blocked Work

Default workflows include Backlog, Todo, In Progress, Blocked, Done, and Cancelled. Move waiting work into the red Blocked column by dragging a card, or choose Blocked in the issue's status picker. Add the reason in the description or a comment, then move the issue back when the blocker is resolved.

Blocked belongs to the Started lifecycle group: it is unfinished work, included in active issue lists and cycle work in progress, and does not count as completed or cancelled. Status filters and saved views can show Blocked alone. API and MCP clients discover its team-specific ID through the status list and can use the usual status update or transition_issue tool.

Existing teams receive Blocked without changing their other statuses or default. A team's existing custom Blocked status keeps its own configuration; check its lifecycle group if your team uses a different workflow.

Search

Press Cmd+K (or Ctrl+K) to open the global search dialog. Search works across issues and documents:

  • Keyword search — matches individual words in titles and descriptions
  • Semantic search (Pro+) — finds conceptually related items even without shared keywords, powered by vector embeddings. An AI badge appears when semantic search is active, and similar results are shown with a similarity percentage.

See AI Search for details on how hybrid search works.

Filtering

The filter bar supports multiple criteria that can be combined:

  • Status — filter by one or more statuses
  • Priority — filter by priority level
  • Assignee — filter by assigned team member
  • Label — filter by one or more labels
  • Team — filter by team
  • Project — filter by project
  • Cycle — filter by sprint cycle
  • Due date — filter by due date

Filter state is stored in the URL, so you can share filtered views with teammates by copying the link.

Saved Views

Save any filter configuration as a View. Navigate to the Views page in the sidebar to see all saved views and switch between them. Views are shared across the workspace.

Detail Panel

Clicking an issue opens a side panel with the full details:

  • Rich-text description with Tiptap editor
  • Comment thread with reactions and threaded replies
  • Activity log showing all changes
  • Fields: status, priority, assignee, labels, project, cycle, due date

Rich Text Descriptions

Issue descriptions support full rich-text formatting powered by the same Tiptap editor used in Documents. Click the description area to enter edit mode.

The editor supports:

  • Text formatting — bold, italic, strikethrough, inline code, highlight
  • Headings — H1, H2, H3 via toolbar or Markdown shortcuts
  • Lists — bullet lists, numbered lists, task lists with checkboxes
  • Code blocks — syntax-highlighted with language detection
  • Block quotes, links, images, and dividers

Descriptions created via the MCP server or API using Markdown syntax are automatically parsed and rendered as rich text. Click to edit, then click outside or press Esc to save and return to view mode.

Context Menu

Right-click any issue (or press the … button) to access quick actions: change status, set priority, assign, add labels, copy link, or delete.

Bulk Actions

Select multiple issues with Shift+click, then use the bulk action bar to update status, priority, assignee, or labels for all selected issues at once.