doc/user/project/issue_board.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Issue boards provide a visual way to manage and track work in GitLab. Issue boards:
Your issues appear as cards in vertical lists, organized by their assigned labels, milestones, iterations, assignees or status.
Add metadata to your issues, then create the corresponding list for your existing issues. When you're ready, you can drag your issue cards from one list to another.
Issue boards can power common frameworks like Kanban and Scrum.
To let your team members organize their own workflows, use multiple issue boards. This allows creating multiple issue boards in the same project.
Different issue board features are available in different GitLab tiers:
| Tier | Number of project issue boards | Number of group issue boards | Configurable issue boards | Assignee lists |
|---|---|---|---|---|
| Free | Multiple | 1 | {{< no >}} | {{< no >}} |
| Premium | Multiple | Multiple | {{< yes >}} | {{< yes >}} |
| Ultimate | Multiple | Multiple | {{< yes >}} | {{< yes >}} |
Read more about GitLab Enterprise features for issue boards.
<i class="fa-youtube-play" aria-hidden="true"></i> Watch a video presentation of the issue board feature.
<!-- Video published on 2020-04-02 -->Multiple issue boards allow for more than one issue board for:
Multiple issue boards are great for large projects with more than one team, in which a repository hosts the code of multiple products and when you want to create boards to power different workflows across the software development lifecycle.
Using the search box at the top of the menu, you can filter the listed boards.
When you have ten or more boards available, a Recent section is also shown in the menu, with shortcuts to your last four visited boards.
When you're revisiting an issue board in a project or group with multiple boards, GitLab automatically loads the last board you visited.
Prerequisites:
To create a new issue board:
Prerequisites:
To delete the open issue board:
If the board you've deleted was the last one, a new Development board is created.
You can tailor GitLab issue boards to your own preferred workflow. For workflow-based documentation, see the plan and track your work tutorial.
With the GitLab Flow you can discuss proposals in issues, label them, and organize and prioritize them with issue boards.
For example, let's consider this simplified development workflow:
If you have the labels Backend, Frontend, Staging, and Production, and an issue board with a list for each, you can:
In a Scrum team, use multiple issue boards so that each scrum team has their own board. On the Scrum board, you can move issues through each part of the process. For example: To Do, Doing, and Done.
To quickly assign issues to your team members:
An issue board represents a unique view of your issues. It can have multiple lists with each list consisting of issues represented by cards.
A list is a column on the issue board that displays issues matching certain attributes. In addition to the default "Open" and "Closed" lists, each additional list shows issues matching your chosen label, assignee, or milestone. On the top of each list you can see the number of issues that belong to it. Types of lists include:
A Card is a box on a list, and it represents an issue. You can drag cards from one list to another to change their label, assignee, or milestone. The information you can see on a card includes:
A swimlane is a horizontal grouping of issues on the issue board, for example by parent epic.
Prerequisites:
When an issue is created, the system assigns a relative order value that is greater than the maximum value of that issue's project or top-level group. This means the issue is at the bottom of any issue list that it appears in.
When you visit a board, issues appear ordered in any list. You're able to change that order by dragging the issues. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions.
Any time you drag and reorder the issue, its relative order value changes accordingly.
Then, any time that issue appears in any board, the ordering is done according to
the updated relative order value. If a user in your GitLab instance
drags issue A above issue B, the ordering is maintained when these two issues are subsequently
loaded in any board in the same instance.
This could be a different project board or a different group
board, for example.
This ordering also affects issue lists. Changing the order in an issue board changes the ordering in an issue list, and vice versa.
In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. To enable or disable focus mode, in the upper-right corner, select Toggle focus mode ({{< icon name="maximize" >}}).
Accessible at the group navigation level, a group issue board offers the same features as a project-level board. It can display issues from all projects that fall under the group and its descendant subgroups.
Users on GitLab Free can use a single group issue board.
GitLab issue boards are available on the GitLab Free tier, but some advanced functionality is present in higher tiers only.
{{< details >}}
{{< /details >}}
An issue board can be associated with a milestone, labels, assignee, weight, and current iteration, which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need.
You can define the scope of your board when creating it or by selecting the Configure board ({{< icon name="settings" >}}) button. After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer filter through these in the search bar. To do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board.
If you don't have editing permission in a board, you're still able to see the configuration by selecting Board configuration ({{< icon name="settings" >}}).
{{< details >}}
{{< /details >}}
As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists.
Prerequisites:
To add an assignee list:
Now that the assignee list is added, you can assign or unassign issues to that user by moving issues to and from an assignee list. To remove an assignee list, just as with a label list, select the trash icon.
{{< details >}}
{{< /details >}}
You can create milestone lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board.
Prerequisites:
To add a milestone list:
To change the milestone of issues, drag issue cards to and from a milestone list.
{{< details >}}
{{< /details >}}
You can create lists of issues in an iteration.
Prerequisites:
To add an iteration list:
To change the iteration of issues, drag issue cards to and from an iteration list.
{{< details >}}
{{< /details >}}
{{< history >}}
work_item_status_feature_flag. Enabled by default.work_item_status_feature_flag removed.{{< /history >}}
Create lists of issues that have a specific status. Status lists help you organize issues by their workflow stage, such as In progress or Done.
For more information, see the status section.
Status lists behave differently from other list types:
Prerequisites:
To add a status list:
The status list is added to the board and displays issues with that status.
To change the status of issues, drag issue cards to and from a status list.
{{< details >}}
{{< /details >}}
With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. This feature is available both at the project and group level.
Prerequisites:
To group issues by epic in an issue board:
You can then edit issues without leaving this view and drag them to change their position and epic assignment:
{{< details >}}
{{< /details >}}
The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, especially in combination with assignee lists.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
You can set a work in progress (WIP) limit for each issue list on an issue board. When a limit is set, the current state and configured limit are shown in the board list header.
A line in the list separates items within the limit from those in excess of the limit. You cannot set a WIP limit on the default lists (Open and Closed).
GitLab supports two types of WIP limits:
Items: Limits the number of issues in a list regardless of their weight. The board header shows the number of issues in the list and the item limit.
For example, if there are 4 issues and an item limit of 3, the header shows 4/3.
Weight: Limits the total weight of issues in a list. The board header shows the total weight of issues in the list and the weight limit.
For example, if there are issues with weights adding up to 8 and a weight limit of 5, the header shows 8/5.
Examples:
Prerequisites:
To set a WIP limit for a list, in an issue board:
To remove a WIP limit, select Remove limit.
{{< details >}}
{{< /details >}}
If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked status.
When you hover over the blocked icon ({{< icon name="entity-blocked" >}}), a detailed information popover is displayed.
You can edit an issue without leaving the board view. To open the right sidebar, select an issue card (not its title).
Prerequisites:
You can edit the following issue attributes in the right sidebar:
When you select an issue card from the issue board, the issue opens in a details panel. There, you can edit all the fields, including the description, comments, or related items.
{{< history >}}
{{< /history >}}
You can create a new list between two existing lists or at the right of an issue board.
To create a new list between two lists:
In the top bar, select Search or go to and find your project.
Select Plan > Issue boards.
Hover or move keyboard focus between two lists.
Select New list. The new list panel opens.
Choose the label, user, milestone, iteration, or status to base the new list on.
Select Add to board.
The new list is inserted in the same position on the board as the new list panel.
To move and reorder lists, drag them around.
Alternatively, you can select the New list at the right end of the board. The new list is inserted at the right end of the lists, before Closed.
Removing a list doesn't have any effect on issues and labels, as it's just the list view that's removed. You can always create it again later if you need.
Prerequisites:
To remove a list from an issue board:
Prerequisites:
If your board is scoped to one or more attributes, go to the issues you want to add and apply the same attributes as your board scope.
For example, to add an issue to a list scoped to the Doing label, in a group issue board:
Doing label.The issue should now show in the Doing list on your issue board.
When an issue should no longer belong to a list, you can remove it.
Prerequisites:
The steps depend on the scope of the list:
You can use the filters on top of your issue board to show only the results you want. It's similar to the filtering used in the issue tracker.
Prerequisites:
You can filter by the following:
When filtering issues in a group board, keep this behavior in mind:
When you edit issues individually using the right sidebar, you can additionally select the milestones and labels from the project that the issue is from.
You can move issues and lists by dragging them.
Prerequisites:
To move an issue, select the issue card and drag it to another position in its current list or into a different list. Learn about the possible effects in dragging issues between lists.
To move a list, select its top bar, and drag it horizontally. You can't move the Open and Closed lists, but you can hide them when editing an issue board.
{{< history >}}
{{< /history >}}
You can move issues to the top of the list with a menu shortcut.
Your issue is moved to the top of the list even if other issues are hidden by a filter.
Prerequisites:
To move an issue to the start of the list:
{{< history >}}
{{< /history >}}
You can move issues to the bottom of the list with a menu shortcut.
Your issue is moved to the bottom of the list even if other issues are hidden by a filter.
Prerequisites:
To move an issue to the end of the list:
To move an issue to another list, select the issue card and drag it onto that list.
When you drag issues between lists, the result is different depending on the source list and the target list.
| To Open | To Closed | To label B list | To assignee Bob list | |
|---|---|---|---|---|
| From Open | - | Close issue | Add label B | Assign Bob |
| From Closed | Reopen issue | - | Reopen issue and add label B | Reopen issue and assign Bob |
| From label A list | Remove label A | Close issue | Remove label A and add label B | Assign Bob |
| From assignee Alice list | Unassign Alice | Close issue | Add label B | Unassign Alice and assign Bob |
A few things to remember:
There was a problem fetching users on group issue board when filtering by Author or AssigneeIf you get a banner with There was a problem fetching users error when filtering by author or assignee on
group issue board, make sure that you are added as a member to the current group.
Non-members do not have permission to list group members when filtering by author or assignee on issue boards.
To fix this error, you should add all of your users to the top-level group with the Guest, Planner, Reporter, Developer, Maintainer, or Owner role.
If you see issue board not loading and timing out in UI, use Rails console to call the Issue Rebalancing service to fix it:
Run these commands:
p = Project.find_by_full_path('<username-or-group>/<project-name>')
Issues::RelativePositionRebalancingService.new(p.root_namespace.all_projects).execute
To exit the Rails console, type quit.