IEEE SA Open
Gitlab Project Management

Gitlab Project Basics

Managing Projects with Gitlab

The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow. It can be used as a Kanban or a Scrum board.

The Issue Board pairs issue tracking and project management, keeping everything in the same place, so that you don't need to jump between different platforms to organize your workflow.

Issue boards show your issues as cards in vertical lists, organized by their assigned labels. They can help you to visualize and manage your entire process in GitLab. Add labels, and then create the corresponding list for your existing issues. When you're ready, you can drag your issue cards from one step to another one.

An issue board will show you what issues your team is working on, who is assigned to each issue, and where in the workflow those issues are.

To let your team members organize their own workflows, use multiple issue boards.

Use Cases for Issue Boards

You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards.

Use cases for a Single Issue Board

With the GitLab Workflow you can discuss proposals in issues, categorize them with labels, and from there, organize and prioritize them with issue boards.

For example, let's consider this simplified development workflow:

You have a repository that hosts your application's codebase, and your team actively contributes code.
Your backend team starts working on a new implementation, gathers feedback and approval, and passes it over to the frontend team.
When front end is complete, the new feature is deployed to a staging environment to be tested.
When successful, the new code is deployed to production.

If you have the labels [Backend], [Frontend], [Staging], and [Production], and an issue board with a list for each, you can:

Visualize the entire flow of implementations from the beginning of the development life cycle through deployment to production.
Prioritize the issues in a list by moving them vertically.
Move issues between lists to organize them according to the labels you've set.
Add multiple issues to lists in the board by selecting one or more existing issues.

Use Cases for Multiple Issue Boards

With multiple issue boards, each team can have their own board to organize their workflow separately.

Scrum Team
With multiple issue boards, each team has one board. Now you can move issues through each part of the process. For instance: from [To Do] to [Doing] to [Done].

Organization of Topics
Create lists to order issues by topic and quickly change them between topics or groups, such as between [UX], [Frontend], and [Backend]. The changes are reflected across boards, as changing lists updates the labels on each issue accordingly.

Advanced Team Handoff
For example, suppose we have a UX team with an issue board that contains:
- To Do
- Doing
- Frontend

When finished with something, they move the card to Frontend. The Frontend team's board looks like:
- Frontend
- Doing
- Done

Cards finished by the UX team automatically appear in the Frontend column when they are ready for them.

Quick Assignments
Create lists for each of your team members and quickly drag issues onto each team member's list.

Issue Board Terminology

Issue Board
An issue board represents a unique view of your issues. It can have multiple lists, with each list consisting of issues represented by cards.

List
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. On the top of each list you can see the number of issues that belong to it. Types of lists include:

Open (default): all open issues that do not belong to one of the other lists. [Open] always appears as the leftmost list.
Closed (default): all closed issues. [Closed] always appears as the rightmost list.
Label list: all open issues for a label. A list with the appropriate label must be added for this to function.

Card
A card looks like a box on a list, and it represents an issue. You can drag cards from one list to another to change their label. The information you can see on a card includes:

Issue title
Associated labels
Issue number
Assignee

Permissions

Users with the Reporter and higher roles can use all the functionality of the Issue Board feature to create or delete lists and drag issues from one list to another.

How Issues are Ordered in a List

Issues on each board appear in an order in each list. You're able to change that order by dragging the issues up or down. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions.

The first time a given issue appears in any board (that is, the first time a user loads a board containing that issue), it is ordered in relation to other issues in that list according to label priority. At this point, that issue is assigned a relative order value by the system, representing its relative order with respect to the other issues in the list. Any time you reorder that issue by dragging, its relative order value changes accordingly.

Also, any time that issue appears in any board, the updated relative order value is used for the ordering. It's only the first time an issue appears that it takes its ordering from the priority order mentioned above. This means that if two issues are reordered by any user in a given board inside your GitLab instance, the new order is maintained any time those two issues are subsequently loaded in any board in the same instance (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.

Creating an Issue Board

To create a new issue board:

Click the dropdown with the current board name in the upper left corner of the Issue Boards page.

Click [Create new board] (highlighted in green above).

Enter the new board's name.

Deleting an Issue Board

To delete the currently active issue board:

Click the dropdown with the current board name in the upper left corner of the Issue Boards page.

Click Delete board.

Click Delete to confirm.

Focus Mode

Click the button with four arrows at the top right beside the dark green [Add Issues] button to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.

Actions You Can Take on an Issue Board

Create a new list.
Delete an existing list.
Add issues to a list.
Remove an issue from a list.
Filter issues that appear across your issue board.
Create workflows. (See below.)
Drag issues between lists.
Drag and reorder the lists.
Change issue labels (by dragging an issue between lists).
Close an issue (by dragging it to the Done list).

If you're not able to do some of the things above, check to make sure you have been granted the correct permissions.

Create Workflows

By reordering your lists, you can create workflows. As lists in issue boards are based on labels, this process works out of the box with your existing issues.

A typical workflow using an issue board would be:

You have created and prioritized labels so that you can easily categorize your issues.
You have a bunch of issues (ideally labeled).
You visit the issue board and start creating lists to create a workflow.
You move issues around in lists so that your team knows who should be working on what issue.
When the work by one team is done, the issue can be dragged to the next list so someone else can pick it up.
When the issue is finally resolved, the issue is moved to the Done list and gets automatically closed.

For example, you can create a list based on the label of Frontend and one for Backend. A designer can start working on an issue by adding it to the Frontend list. That way, everyone knows that this issue is now being worked on by the designers.

Then, once they're done, all they have to do is drag it to the next list, Backend, where a backend developer can eventually pick it up. Once they're done, they move it to Done, to close the issue.

This process can be seen clearly when visiting an issue, since with every move to another list the label changes and a system note is recorded.

Drag issues between lists

When you drag issues between lists, different behavior occurs depending on the source list and the target list.

Tips and Tricks

A few things to remember:

Moving an issue between lists removes the label from the list it came from and adds the label from the list it goes to.
An issue can exist in multiple lists if it has more than one label.
Lists are populated with issues automatically if the issues are labeled.
Clicking the issue title inside a card takes you to that issue.
Clicking a label inside a card quickly filters the entire issue board and show only the issues from all lists that have that label.
For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next 20 appear.

How to Use Labels

As the quantity of issues and merge requests increases in GitLab, it's more and more challenging to keep track of those items. This is where labels come in. They help you organize and tag your work so you can track and find the work items you're interested in.

Labels are a key part of issue boards. With labels you can:

Categorize issues, and merge requests using colors and descriptive titles like bug, feature request, or docs.
Dynamically filter and manage issues and merge requests.
Search lists of issues and merge requests as well as issue boards.

Project Labels and Group Labels

There are two types of labels in GitLab:

Project labels can be assigned to issues and merge requests in that project only.
Group labels can be assigned to issues and merge requests in any project in the selected group or its subgroups.

Assigning and Unassigning Labels

Every issue and merge request can be assigned any number of labels. The labels are managed in the right sidebar of the details tissue view, where you can assign or unassign labels as needed.

To assign a label to an issue or merge request:

In the label section of the sidebar, click Edit.
In the list, click the labels you want. Each label is flagged with a checkmark.
Find labels by entering a search query in the box by the magnifying glass icon, then click on them. You can search repeatedly and add more labels.
Click X or anywhere outside the label section and the labels are applied.

Creating Labels

Users with a permission level of Reporter or higher are able to create and edit labels.

Project Labels

View the project labels list by going to the project and navigating the menu at the left to Project Information and then to Labels in the exposed menu. The list includes all labels that are defined at the project level, as well as all labels inherited from the immediate parent group. You can filter the list by entering a search query at the top and clicking the magnifying glass icon.

To create a new project label:

Click the New Label button (as shown on the screen above) to open the New Label screen.

Title
This text will appear on the label. Try to make it concise and clear.

Description
You can enter a description here to help your team better understand the purpose. This is optional.

Background Color
Select a background color by clicking on the available colors, or input a hex color value for a specific color.

Click the Create Label button to create the label.

You can also create a new project label from within an issue or merge request. In the label section of the right sidebar of an issue or a merge request:

Click Edit (highlighted by the purple rectangle above) to open the Assign Labels menu.
Click “Create project label” (highlighted by the red-orange rectangle above).

Name New Label
Fill in the Name New Label field. Note that you can’t specify a description if creating a label this way. You can add a description later by editing the label (see below).

Assign Custom Color
Optionally, select a color by clicking on the available colors, or input a hex color value for a specific color in the Assign Custom Color field.

Add List
Click this checkbox if you would like to create a list on your issue board with this label as the descriptor.

Click Create.

Managing Project Labels

Editing a Label

Once created, you can edit a label by clicking the pencil icon.

You can also delete a label by clicking the three dots next to the Subscribe button and selecting Delete.

Caution: If you delete a label, it is permanently deleted. You will not be able to undo the deletion, and all references to the label will be removed from the system.

Promote a Project Label to a Group Label

If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label.

If other projects in the same group have a label with the same title, they will all be merged with the new group label. If a separate group label with the same title exists, it will also be merged.

All issues, merge requests, issue board lists, issue board filters, and label subscriptions with the old labels will be assigned to the new group label.

Caution: Promoting a label is a permanent action, and cannot be reversed.

To promote a project label to a group label:

Navigate to the project. In the menu at the left, navigate to Project information and then to the Labels in the project.
Click on the three dots next to the Subscribe button and select Promote to Group Label.

Group Labels

View the Group Labels list by going to the group and navigating the menu at the left to Group Information and then to Labels. The list includes all labels that are defined at the group level only. It does not list any labels that are defined in projects. You can filter the list by entering a search query at the top and clicking the magnifying glass icon.

To create a group label, navigate the menu at the left to Group Information and then to Labels and follow the same process as creating a project label.

Label Priority

Labels can have relative priorities, which are used in the Label Priority and Priority sort orders of the Issue and Merge Request List pages. Prioritization for both Group and Project Labels happens at the project level, and cannot be done from a Group Label list.

From the Project Label list page, star a label to indicate that it has priority.

Drag starred labels up and down the list to change their priority, where higher in the list means higher priority.

Sorting Issues and Merge Requests

On the Merge Request and Issue List pages (for both groups and projects) you can sort by Label Priority or Priority.

By Label Priority

If you sort by Label Priority, GitLab uses this sort comparison order:

Items with a higher priority label.
Items without a prioritized label.

Ties are broken arbitrarily. Note that only the highest prioritized label is checked, and labels with a lower priority are ignored.

By Priority

If you sort by Priority, GitLab uses this sort comparison order:

Items with milestones that have due dates, where the soonest assigned milestone is listed first.
Items with milestones with no due dates.
Items with a higher priority label.
Items without a prioritized label.

Ties are broken arbitrarily.