How do I create and organize issues?

Choosing between GitHub and Zenhub issues

Before creating your first issue, understanding when to use each type helps you organize work effectively and maintain proper tool integration.

Choose GitHub Issues when:

• The work involves code changes, bug fixes, or feature development
• You need the issue to appear in pull requests and GitHub's native views
• Your team uses GitHub's milestone or project features
• You want developers to access issues directly from the repository
• The work needs to sync with GitHub's notification system

Choose Zenhub Issues when:

• The work is project management or planning focused
• You're coordinating across multiple repositories
• The task doesn't require code changes (design, documentation, planning)
• You want to keep strategic work separate from development execution
• You need Zenhub-specific organizational features

The creation interfaces look different too. GitHub issues include templates (if configured), GitHub-specific metadata like milestones and projects, and fields that sync bidirectionally between platforms. Zenhub issues have a cleaner interface focused on project management metadata like issue types, estimates, parent relationships, and sprint assignments.

Creating your first issue

Once you've decided on the issue type, Zenhub gives you several ways to create issues depending on your workflow.

Using the main Create button

Click the green "Create" button in the top-right corner of your Zenhub workspace. This opens a dropdown menu with options:

• GitHub Issue - Developer task
• Zenhub Issue - Multi-disciplinary task
• Release - A group of epics and issues
• Milestone - Weekly or bi-weekly sprint/goals
• Pipeline - A step in the workflow
• Sprints - Weekly or bi-weekly team goals

Select either GitHub Issue or Zenhub Issue to open the creation window with your issue title at the top, description area in the middle, and metadata options on the right sidebar.

Choosing your repository

If your workspace connects to multiple GitHub repositories, you'll see a "Create In" dropdown that lets you select which repository should contain your new issue. Each user can set their preferred default repository in workspace settings, but you can always override this choice during creation.

 

Using issue templates

For GitHub issues, you can select from available templates using the Template dropdown. These templates come from your GitHub repository settings and help standardize information collection for common issue types like bug reports, feature requests, or user stories. You can filter through available templates or select "None" to create a blank issue.

 

Quick creation options

You can also create issues directly in your Work Tracker by clicking the blue "+" button at the top of any pipeline column. This creates the issue and immediately places it in that workflow stage.

Issues created directly in GitHub automatically sync to your Zenhub workspace, appearing with their GitHub metadata intact.

Writing clear issue descriptions

The description editor is where you provide context and requirements for your team.

Markdown formatting options

The description editor includes a comprehensive toolbar with formatting options:

• Headers (H1, H2, H3) for structuring content and creating clear sections
• Bold and italic text for emphasis and highlighting key information
• Quotes for highlighting important information or requirements
• Code blocks for technical details, commands, or code snippets
• Links to connect related resources, documentation, or other issues
• Bullet lists for grouping related items or requirements
• Numbered lists for sequential steps or prioritized items
• Task lists with checkboxes for tracking completion of specific items

AI-powered assistance

As you write your issue title, Zenhub's AI Suggestions feature can help generate relevant content and labels based on your title and description context. This helps ensure you include important details and apply consistent categorization.

Use the Generate acceptance criteria feature to automatically create acceptance criteria in Behavior-Driven Development (BDD) format. This AI-powered feature analyzes your issue title and description to suggest relevant acceptance criteria that define when the work is complete.

Writing effective content

Include context and background information so teammates understand not just what needs to be done, but why it matters. Link to related resources, designs, documentation, or other issues that provide additional context. You can also attach files by dragging and dropping them into the description area.

Well-written descriptions eliminate back-and-forth questions and help team members work independently.

Setting up essential metadata

The right sidebar contains metadata fields that help organize and prioritize your work.

Pipeline and placement

Every issue gets placed in a pipeline representing its current workflow status. By default, new issues are created in your leftmost pipeline unless you specify otherwise. Choose a different starting pipeline when you know exactly where the work should begin in your workflow.

Assignees and ownership

Add team members who will work on the issue. You can assign multiple people for collaborative work, but clear ownership prevents confusion about responsibility. Unassigned issues show "No one - assign yourself" as a quick self-assignment option.

Issue types and relationships

Set the issue type (Task, Epic, Bug, Story, Enhancement) and establish parent-child relationships for both GitHub and Zenhub issues. Setting a parent helps organize work hierarchically and provides context about how individual tasks contribute to larger goals.

Estimates and planning

Story points help with sprint planning and capacity tracking. Use the Fibonacci sequence (1, 2, 3, 5, 8, 13, 21) to indicate relative complexity and effort. You can set initial estimates during creation, focusing on consensus-based estimation rather than individual time predictions.

After creating issues, access Planning Poker from the issue view by clicking the "+" next to "Planning poker" in the estimates section. This allows multiple team members to vote on estimates simultaneously - each member selects their estimate privately, then all votes are revealed at once. This consensus-based approach produces more accurate estimates by incorporating different perspectives.

Sprint and release coordination

Add issues to specific sprints during planning sessions to establish clear delivery commitments. Release assignment helps coordinate feature rollouts and provides stakeholders with visibility into what's included in each product release.

Organizing with labels

Labels provide flexible categorization that helps your team scan and prioritize work quickly.

Priority labels

Establish a simple, color-coded priority system. Use red for urgent items, yellow for medium priority work, and green for lower priority tasks. Apply priority labels consistently during creation so team members can identify critical work during standups and sprint planning.

Component labels

Tag work by functional area using labels like "frontend," "backend," or "design." These help during sprint planning when balancing workload across different skill sets and help team members find work matching their expertise.

Workflow labels

Use labels like "blocked," "ready-for-review," or "needs-info" to provide status context beyond pipeline position. These become especially valuable during team meetings when discussing what's preventing progress on different work items.

Label management

Keep your label list focused and manageable with 10-15 labels maximum. Use consistent colors across similar label types and review labels periodically to consolidate similar ones and remove unused labels. Apply 2-4 labels per issue typically - one priority label, one component label, and one or two workflow labels.

Understanding your Work Tracker

Once created, issues appear as cards in your Work Tracker, showing key information at a glance.

Issue cards

Issue cards display the title, labels, assignee avatars, story points, and current pipeline. High priority issues show with a pin icon and red border, automatically appearing at the top of their pipeline column. Hover over cards to access quick actions like editing metadata, moving between pipelines, or accessing the full issue view.

Pipeline workflow

Issues move from left to right through pipeline columns representing your workflow stages. Drag and drop issues between pipelines to update their status. This visual flow helps identify bottlenecks and coordinate handoffs between team members.

Customize pipeline names and structure to match your actual process. Common workflows include To Do → In Progress → Review → Done, but adapt these stages to reflect how your team actually works.

Daily issue management patterns

Develop consistent workflows for creating and managing issues as part of your regular process.

During planning sessions

Create issues with clear titles and enough description for team members to understand scope and requirements. Set appropriate metadata including estimates, labels, and assignments during planning conversations when context is fresh. Use the creation process to clarify requirements and expectations.

As work progresses

Update issue status by moving cards between pipelines as work progresses. Add comments with progress updates, blockers, or questions that need team input. Keep metadata current, especially when scope or assignments change.

Sprint and release coordination

During sprint planning, create issues with sprint assignments and appropriate estimates. Use release assignments to group related work and coordinate feature deliveries. Review and update issue organization regularly to reflect changing priorities and discoveries.

Well-organized issues make sprint planning more efficient and help teams maintain focus on delivery commitments.

FAQ