8 Track and Manage Tasks, Defects, and Features

Use issues to track new feature requests or enhancements, assign tasks to team members, or file bugs.

You can create, update, and search issues from the Issues page or from Agile boards. You can also use REST APIs to create, retrieve, and update issues.

In a project, you can create an issue as a Task, Defect, or a Feature. If your team uses an Agile Scrum board to update issues, Epic and Story types of issues are also available. An Epic is a larger issue typically composed of multiple smaller sub-issues or Story issues. An Epic must have sub-issues and can span multiple sprints.

These are the key steps you’ll perform to create and track issues:

  1. As the project owner, start by setting up products, components, and releases for your project, which you'll need when you start identifying tasks, defects, and features.

    If the default set of issue fields don’t meet your requirements, create custom fields.

  2. Create issues and assign them to your team members.

  3. Update issues, either from the Issues page or from an Agile board.

Issue Types

An issue can be categorized into task (or action), defect (or bug), and feature (or enhancement).

You can create these types of issues:

Issue Type Description

Task Task

Indicates a task, which means an action is required.

A Task type issue could be an action such as a piece of work that must be completed within a certain time, or a simple function to be performed.

Defect Defect

Indicates a defect, which means a bug or a fault in the product. This is the default issue type.

A Defect type issue could be an error or a flaw that prevents the software from working correctly, or creates an unexpected output.

Feature Feature

Indicates a new feature or an enhancement request.

A Feature type issue could be a request to add a new aspect or characteristic to the product, or enhance an existing feature.

Epic Epic

Indicates an Epic, a unit of work that cannot be completed in one sprint. It can contain any other types of sub-issues necessary to complete that work.

An Epic is a larger issue, typically with multiple smaller sub-issues or stories. An epic can span multiple sprints and must have sub-issues (as stories or other issues).

Story Story

Indicates a Story, a sub-issue of a parent epic issue.

The story issues of an epic issue can be allotted to different sprints in an Agile board.

Create Issues

You can create an issue from the Issues page or from the REST API. When you create an issue, it gets assigned a unique ID and is added to the issues list on the Issues page.

When you create an issue, you specify its summary, type, severity and priority, due date, tags, and release. You can assign the issue to a team member or to yourself, or leave the field blank to assign the issue later to a team member.

Create an Issue from the Issues Page

  1. In the navigation menu, click Issues Issues.
  2. Click New Issue.
  3. On the New Issue page, in Summary and Description, enter the issue’s title and description.
  4. In Details, specify the issue type, its severity and priority, product details, release, ownership, and project tags.
  5. In Time, specify the due date and estimate (in days).
    One day is estimated of 8 hours. To specify 3 hours, enter 0.375. To specify 2 days and 2 hours, enter 2.250.
  6. In Agile, specify the effort estimate in Agile story points.
  7. If there are any custom fields defined in your project, fill in the details, as required.
  8. Click Create Issue.

Search Issues

You can search for issues using the pre-defined filters under Standard Searches, My Searches, Shared Searches, or Global Searches. If you can’t find the issue, you can run a basic search or an advanced one.

To run a basic search, use the Search Issues box in the upper-right corner of the Issues page. You can search for a term in the summary, description, or comments of issues. To clear the search term, click Clear Filter the Clear Filter icon.

To run an advanced search, use the Advanced Searches link. You can search for issues using various parameters such as sprints, product, version, date, owner, type, and priority.

To save the search query as a filter, click Save this search. To see the search query expression, click Show Search String. Later, if you want to edit the search query, click Edit this search.

Save a Custom Search

You can save basic or advanced search queries as a custom search filters that can be used later:

  1. On the Issues page, run a basic or an advanced search.
  2. On the search results page, click Save this search.
  3. In the Save Search dialog box, enter the search name.

    The custom search filter is available to you only. To share the search filter with project members, in the Save Search dialog box, select the Shared check box. In Share with the following users, select the users with whom you want to share the search query.

    To share the search filter with all project members, select the Share with everyone check box.

  4. Click OK.
The location where the query filters can be found is determined by the way you configured the search:
  • If you didn’t select the Shared check box, the search query appears as a filter under My Searches.
  • If you selected the Shared check box, the search query appears as a filter under Shared Searches.
  • If you selected the Share with everyone check box, the search query appears as a filter under Global Searches.

To edit a custom search query, mouse over the query under My Searches and click Edit the Edit icon.

To delete a custom search query, mouse over the query under My Searches and click Delete the Delete icon.

Share Custom Search Filters

You can share your existing custom search filters with other project members, which they can use to view the issues as you want:

Element Description

Share a search filter with specific project members

  1. In My Searches, mouse over the filter link, and click Share the Share icon.

  2. In the Start Sharing Search dialog box, select the project member names in Share with following users.

  3. Click OK.

The filter link moves from My Searches to Shared Searches.

Share a search filter with all project members

  1. In My Searches, mouse over the filter link, and click Share the Share icon.

  2. In the Start Sharing Search dialog box, select the Share with Everyone check box.

  3. Click OK.

The filter link moves from My Searches to Global Searches.

Stop sharing a search filter

  1. In Global Searches or Shared Searches, mouse over the filter link and click Stop Share the Stop Sharing icon.

  2. In the Stop Sharing Search dialog box, click OK.

    If the search query is being used by other project members, the dialog box shows their list.

When you stop sharing a search query, it is removed from the Shared Searches or Global Searches list for all project users.

View and Update Issues

To view or update an issue, click the issue’s summary or the ID link on the Issues page. An issue link could also be found in the recent activities feed, wikis, Agile boards, and merge requests.

While updating an issue, you can change its status, properties, reassign it to another member, and change its priority or severity. You can also add comments in the Comments tab, upload attachments in the Attachments tab, and check the update history of an issue in the History tab. Updates made to issues can also be tracked in the recent activities feed of the Project Home page.

Resolve an Issue

You can resolve an issue as Fixed, Invalid, Duplicate, Will not fix, Works for me, or Need info:

  1. Click the issue link to open it in the Issues page.
  2. From the Status drop-down list, select Resolved.
  3. From the Resolution drop-down list, select the resolution.
    Sub-status Indicates ...

    Fixed

    The issue has been fixed and is awaiting feedback from the QA team.

    After verifying the fix, the QA team sets the issue’s status to Verified or Closed.

    Invalid

    The issue isn’t a valid issue.

    Will not fix

    The issue won’t be fixed.

    Duplicate

    The issue is a duplicate of an existing issue.

    Enter the issue ID of the existing issue in Duplicate Of.

    Works for me

    The issue cannot be reproduced.

    Need info

    The current issue description isn't sufficient to reproduce the issue; more information is required.

Mark an Issue as Duplicate

If find a duplicate issue, mark it as a duplicate and specify the original issue:

  1. Click the issue link to open it in the Issues page.
  2. From the Status drop-down list, select Resolved.
  3. From the Resolution drop-down list, select Duplicate.
  4. In Duplicate Of, enter the original issue ID or the summary text, and select the original issue.
  5. Click Save.

Update Time Spent on an Issue

When you work on an issue, create a time spent entry each time you update the issue:

  1. Click the issue link to open it in the Issues page.
  2. In the Time section, click Add Time Spent.
  3. In the Add Time Spent dialog box, in Time Spent, specify the number of days you’ve spent on the issue.
  4. To subtract the value specified in Time Spent from the existing value of Remaining (if set), use the default Reduce remaining ... days by entered Time Spent option.

    If Remaining isn’t set, then the value specified in Time Spent is subtracted from Estimate. The option is disabled if the Estimated field isn’t set.

    To specify the remaining days manually, select the Set to option and specify the remaining estimate.

  5. In Comment, add a comment.
  6. Click OK.
The Time Spent Log section shows the time spent entry of the time spent and updates the graph.
  • To edit the time spent entry, click Edit the Edit Time Spent icon and update the fields in the Edit Time Spent dialog.

  • To remove a time spent entry, click Remove the Remove Time Spent icon and update the fields in the Update Time Spent dialog box.

The remaining time is adjusted automatically.

Associate an Issue with a Sprint

You can associate an issue with a sprint from the Edit Issue page:

  1. Click the issue link to open it in the Issues page.
  2. In the Agile section, from the Sprint drop-down list, click the search box, and select the sprint from the list.
  3. Click Save.
Note that you can associate only one sprint with an issue.

Create a Relationship Between Issues

You can create a parent-child relationship between issues:

Action How To

Create a child issue to an issue

You can create multiple child issues to an issue:

  1. Click the issue link to open it in the Issues page.

  2. Click + New Sub-issue.

  3. Enter details for the new issue and click Create Issue.

  4. In the header, click the parent issue ID to open the parent issue. In the Associations section, verify the child issue ID.

Add a parent issue to an issue

You can add only one issue as a parent to an issue:

  1. Click the issue link to open it in the Issues page.

  2. In the Associations section, in Parent Issue, enter the issue ID or summary text of the parent issue, and select it.

  3. Click Save.

Update Multiple Issues

On the Issues page, you can update multiple issues in a batch to apply the same update:

  1. In the issues list, press the Ctrl key or the Shift key and click the rows of issues.
    You can also use the Space bar and Up-Down arrow keys to select the issues. To select all issues, click Select All.
  2. Click Update Selected.
  3. On the Mass update page, select the check boxes of fields to update and specify their values.

    Note that the Component check box is enabled when its Product is selected.

    The contents of Found In and Release are determined by Product. If Product isn’t specified, the intersection of all known products is used. For example, if product P1 has Found In set to 1.0, 2.0 and product P2 has Found In set to 1.0, 1.5, then with no product specified, the Found In is set to 1.0. The same logic is applied for Release too.

  4. Click Next.
  5. On the Issues will be Updated page, verify the summary, and click Save.

Issues that fail the update are listed with a description of the error. To resolve errors for multiple issues, select the error issues and click Update Selected. You’ll be taken to the Issues Selected page where the previous changes you made are shown.

If all issues are successfully updated, you’ll be returned to the Issues page.

Watch an Issue

You can set up a watch on an issue and get email notifications when a project user updates an issue, adds a comment, or adds or removes an attachment:

Action How To

Issues assigned to you

By default, you get email notifications of issues assigned to you. If you aren’t getting the email notifications, select the Issue updates, attachments and comments check box in your user preferences page:

  1. In the branding bar, click the user avatar, and select Preferences.

  2. Click the Notifications tab.

  3. Select the Issue updates, attachments and comments check box, if not selected.

  4. To the left of the User Preferences title, click Close Close to return to the last opened page.

Issue created by another user

  1. In the branding bar, click the user avatar, and select Preferences.

  2. Click the Notifications tab.

  3. Select the Issue updates, attachments and comments check box, if not selected.

  4. To the left of the User Preferences title, click Close Close to return to the last opened page.

  5. Open the issue in the Issues page.

  6. In the Details section, in CC, enter and select your name.

    You may also enter other names of other users if you want to notify them too.

  7. Click Save.

To stop watching, remove your name from the CC field.

Issues you created but are assigned to another user

By default, you get email notifications of issues created by you. When you create an issue and assign it to another user, your name is set in the CC field of the issue. Open the issue in the Issues page and verify your name in the CC field of the Details section.

To stop watching, remove your name from the CC field.