Creating Issues
Create and organize GitHub and Zenhub issues, including comments, @mentions, labels, and metadata.
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; or 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); or you want to keep strategic work separate from development execution.
GitHub issues include templates, GitHub-specific metadata, 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.
Comments and @mentions
@mention support depends on the issue type. On GitHub issues, use @username in comments and GitHub sends notifications to mentioned users. On Zenhub issues, @mentioning users in comments is not currently supported. As a workaround, assign the issue to the person who needs to see it, or mention them by name in the comment text without a notification.
Creating issues
Click the green Create button in the top-right corner and select GitHub Issue or Zenhub Issue. This opens the creation window with the title at the top, description area in the middle, and metadata options in the right sidebar.
If your workspace connects to multiple GitHub repositories, use the Create In dropdown to select which repository should contain the new issue.
TIP: Set your default repository in workspace settings to the one you use most frequently. This saves time during issue creation since you won't need to select it manually each time.
For GitHub issues, select from available templates using the Template dropdown. These come from your repository settings and help standardize information collection for common issue types like bug reports or feature requests.
NOTE: Issue templates are specific to each GitHub repository and must be configured in that repository's settings. If you don't see templates, check with your repository administrator about setting them up.
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.
Writing clear descriptions
The description editor supports headers, bold and italic text, quotes, code blocks, links, bullet and numbered lists, and task lists with checkboxes. Include context and background so teammates understand not just what needs to be done, but why it matters.
As you write your title, Zenhub's AI Suggestions feature can help generate relevant content and labels. Use Generate acceptance criteria to automatically create acceptance criteria in BDD format based on your issue title and description.
Setting up metadata
Pipeline and placement
New issues default to your leftmost pipeline unless you specify otherwise. Choose a different starting pipeline when you know exactly where the work should begin.
NOTE: Issues always default to the leftmost pipeline in your Work Tracker. If your team uses a specific pipeline for new work, make sure it's positioned as your leftmost column or remember to change the pipeline during creation.
Assignees
Add team members who will work on the issue. You can assign multiple people for collaborative work. Unassigned issues show a quick self-assignment option.
Issue types and relationships
Set the issue type (Task, Epic, Bug, Story, Enhancement) and establish parent-child relationships. Setting a parent helps organize work hierarchically and provides context about how individual tasks contribute to larger goals.
Estimates
Story points help with sprint planning and capacity tracking. Use the Fibonacci sequence (1, 2, 3, 5, 8, 13, 21) to indicate relative complexity. After creating issues, access Planning Poker from the issue view by clicking the + next to Planning poker in the estimates section. Team members vote privately then all estimates are revealed at once.
TIP: Use Planning Poker for any issue where team members might have different perspectives on complexity. The discussion that happens when estimates differ often reveals important implementation details or potential challenges.
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 release.
Organizing with labels
Labels provide flexible categorization that helps your team scan and prioritize work quickly. A simple system works best: use priority labels (red/yellow/green), component labels (frontend, backend, design), and workflow labels (blocked, ready-for-review, needs-info). Aim for 2–4 labels per issue and keep your total label list to 10–15 maximum.
Too many labels create choice paralysis and reduce their organizational value. If team members struggle to choose appropriate labels quickly, your label system may be too complex.
To edit GitHub issue labels (names, descriptions, or colors), navigate to https://github.com/<your_org>/<your_repo>/labels or go to your repository's Issues tab and click Labels.
FAQ
Q: Should I create GitHub issues or Zenhub issues?
A: Use GitHub issues for code-related work that needs to sync with your repository and appear in pull requests. Use Zenhub issues for project management tasks, planning work, and coordination that doesn't require code changes.
Q: Can I tag or @mention someone in a comment?
A: On GitHub issues, yes — use @username in comments and GitHub will notify that person. On Zenhub issues, user tagging and @mentions are not supported yet. Assign the issue to the person or leave a comment without an @mention as a workaround.
Q: What does the AI acceptance criteria feature do?
A: The Generate acceptance criteria feature analyzes your issue title and description, then suggests relevant acceptance criteria in BDD format. This helps define clear completion criteria and ensures nothing important is missed.
Q: Can I change an issue from GitHub to Zenhub after creation?
A: No. You cannot convert GitHub issues to Zenhub issues. However, you can convert Zenhub issues to GitHub issues using the Convert to GitHub issue option in the three-dot menu.
Q: Can I move an issue to a different repository?
A: Yes, through GitHub's transfer functionality. Open the issue in GitHub, access the issue settings, and select Transfer issue to move it to another repository. See GitHub's transfer documentation for detailed steps.
Q: What other options are available after creating issues?
A: Both GitHub and Zenhub issues have additional options through the three-dot menu. Zenhub issues can be converted to GitHub issues, moved to different workspaces, duplicated, or deleted. GitHub issues can be duplicated but cannot be converted to Zenhub issues.