TABLE OF CONTENTS


What are “Issues”?

“Issues” in agile project management are “tasks” or individual units of work. Typically, a project or Epic is made up of multiple “Issues.” In Zenhub, Issues are represented as cards that live on a Kanban board and are moved from various “Pipelines” depending on their status (e.g., New Issues, Ready for Review, etc.) 



Zenhub Issues vs. GitHub Issues

Zenhub Issues and GitHub Issues both serve the same purpose of representing an individual task that needs to be done. However, the difference between GitHub Issues and Zenhub Issues is who the task is for. Let’s take a look at both issue types: 





GitHub Issues

GitHub Issues are Issues used for software development tasks (e.g., fix a bug, etc.). Using GitHub Issues on your Zenhub board is ideal for software teams as there is no need to duplicate Issues in both your project management system and GitHub. 


GitHub Issues live both inside GitHub and Zenhub, thanks to Zenhub’s native integration with GitHub. So, if you create a GitHub Issue, whether it's in Zenhub or GitHub, expect it to appear in both places. You can also expect any changes you make to your GitHub Issues – whether it's to the label, status, description, comments, etc. – to be reflected in both Zenhub and GitHub. 


Zenhub Issues

Zenhub Issues are issues that can live entirely independently from GitHub, making them ideal for non-engineering tasks. An example task you might create using a Zenhub issue is “Hire a senior developer” or “Create a UX design mockup.”


Note: Zenhub Issues will not appear in GitHub. 



Zenhub Issues to a Workspace

Zenhub Issues have been tied to the organization level and appearing in all workspaces. Which means when a Zenhub Issue is created it appears in all of the Workspaces within that organization. We have now scoped Zenhub Issues to a workspace.


What does that mean going forward?

Going forward when you create a Zenhub issue be sure to take note as to which Workspace you are working in as on the right hand side the issue metadata will show which Workspace this will land in.


What does that mean for our previously created Zh issues?

We have moved your Zenhub issues to the workspace where they were originally created. For older Zenhub Issues where we don’t have that information, we have moved them to a new Workspace called “Migrated Zenhub Issues”. We have sent an email to your admin providing a list of the Zenhub Issues and what Workspace they are now living in. If you want to change the location of the issue feel free to do so within the Zenhub issue metadata where the Workspace selector is. You can find this within the 3 dot menu on the right hand side. This provides you the Zenhub Issue options in which one of them being ‘Move to a different Workspace’. See screenshot


What does this mean for sharing or referencing Zh issues?
We have made sure that the URL issue number will be global therefore the Zenhub Issue can be referred to within a comment or add as a dependency without any complications.


Which Issue type to use?

  • If the work will be done by a developer with a GitHub account - use a GitHub Issue.
  • If the work will be done by anyone else on the team – use a Zenhub Issue.


Converting a Zenhub Issue to a GitHub Issue

If you need to convert a Zenhub Issue to a GitHub Issue, click on the 3 dots on the top right hand side of a Zenhub Issue and select "Convert to GitHub Issue."


How to create Issues in Zenhub

  1. First, make sure you're logged into your Zenhub account and navigate to the board in Zenhub where you want to create the issue.

  2. Click on the "New Issue" button located at the top of your board.

  3. Select whether you want to create a “Zenhub Issue” or a “GitHub Issue.” Note: GitHub Issues are ideal for developers working in GitHub, and Zenhub Issues are ideal for everything else. 

  4. In the "Create Issue" pop-up window that appears, add a title for your issue in the "Title" field. The title should be descriptive and concise so that it's easy to understand what the issue is at a glance.

  5. In the "Description" field, provide a detailed description of the issue you're creating. This should include any relevant information that will help team members understand what needs to be done to resolve the issue.

  6. Use the "Labels" field to categorize your issue. Labels can help you easily identify and sort issues based on their type, priority, or other attributes.

  7. Assign the issue to a team member using the "Assignee" field. This will help ensure that the right person is responsible for resolving the issue.

  1. If your team is using sprints, select which sprint you wish to assign the issue to in the “Sprints” field. 

  2. If there is an Epic or Epics your sprint should fall under, add it under “Epics.”

  3. Once you've filled in all the necessary fields, click the "Create Issue" button to create the issue.


Congratulations, you have created your first issue in Zenhub! You can now organize it into pipelines, add context, collaborate with team members, and track progress using Zenhub's powerful project management features.


Attributes that can be applied to Issues

Pipelines 

Pipelines typically represent the issue’s current status. Assign a pipeline for your Issue, such as New Issues. Zenhub comes with 6 default pipelines which can be customized depending on your workflow.

Labels 

Add a label to your issue. Labels are a core GitHub functionality, and therefore, Zenhub uses a GitHub repo's native label set to populate what available labels exist when navigating Issues in Zenhub. To create new labels, check out our article here.

Assignees

Assign the issue to a member of your team. You can assign up to ten people to an issue.

Sprints

Add the issue to a Zenhub sprint. Sprints allow you to automate your sprint planning process. Learn more here.

Milestone

A GitHub milestone is a fixed length of time when an agreed-upon amount of work will be completed. (Note: Zenhub Sprints are a new entity that we'd recommend using for organizing Sprints instead of Milestones). 

Estimate

Assign a story point estimate to your issue. Story point estimates are unitless scales of measurement that are used to size tasks in comparison to other tasks.

Epics

Attach the issue to an epic. Epics are a theme of work that contain subtasks required to complete the larger goal.

Releases

Add your issue to a release. A release can be considered a long-term goal or a big objective. The project work may be dynamically changing, and it may span multiple sprints.



Grouping Issues to Epics

Issues can be a bit overwhelming without their larger counterpart, Epics. “Epics” in agile project management are larger projects that multiple issues can be grouped into. Here’s how to add them:


  1. In the Zenhub browser or GitHub extension, click on the "Epics" tab located in the left-hand navigation menu.

  2. Click on the "New Epic" button located at the top right corner of the screen.

  3. In the "Create Epic" pop-up window that appears, add a title for your epic in the "Epic Title" field.

  4. Add a description for your epic in the "Description" field, detailing the scope of the work to be done.

  5. Select the Issues that you want to add to the epic by clicking on the checkboxes next to each issue.

  6. Click the "Add to Epic" button located at the bottom right corner of the screen.

  7. In the pop-up window that appears, select the epic you want to add the issues to and click the "Add Issues" button.

  8. Your selected issues will now be added to the epic and will appear in the "Issues" section of the epic.


Note: You can also add Epics directly from the issue’s page. 

For more information on creating Epics in Zenhub, see Introduction to Zenhub Epics. 



Need more help with Zenhub? Contact our support team here.