Day 6: Issues, Agile Planning, and Kanban Boards in GitLab

This chapter explores GitLab's native project management capabilities, focusing on how to plan, track, and execute work using Agile methodologies. By leveraging built-in features such as Issues, Labels, Milestones, and Issue Boards, development teams can eliminate the overhead of third-party tooling and maintain a single source of truth directly within their DevOps platform.

1. The Core Concept of GitLab Issues

In GitLab, the fundamental unit of work is the Issue. While it is easy to think of an issue merely as a "to-do" item or a task, its utility is far broader. An issue serves as a collaborative workspace for ideas, bugs, features, and planning.

What Can an Issue Represent?

• Software Bugs: Tracking defects or unexpected behaviors in the source code.
• New Features: Defining requirements and user stories for upcoming developments.
• Tasks/Requirements: Outlining specific technical or operational steps that need to be executed.
• Discussion Topics: Serving as a forum for team members to deliberate on architectural decisions or project directions.

By consolidating these diverse items into a single system, GitLab provides a unified workspace where planning is directly linked to the underlying codebase.

2. Mapping GitLab to Real-World Agile Tools (Jira Comparison)

In many enterprise DevOps environments, teams use third-party platforms like Jira to track progress, assign tasks, and manage sprints. However, integrating and maintaining external ticketing systems introduces significant challenges:

• Integration Overhead: Setting up and maintaining API connections between the repository and the ticketing tool.
• Context Switching: Developers must constantly jump between their code editor, terminal, GitLab, and Jira.
• Licensing Costs: Paying for separate user seats across multiple platforms.

GitLab solves this by embedding these project management capabilities directly into the repository ecosystem.

Real-Life Analogy: The Ticketing Workflow

Imagine a physical service desk. When a customer reports a problem or requests a service, a ticket is written down on a card. This card contains a title, a description of the problem, and the name of the technician assigned to fix it. As the technician works on the problem, they write updates on the back of the card. Once fixed, the card is moved to a "Completed" box.

In software development, Jira and GitLab Issues act as this digital service desk. They allow managers, architects, and developers to track exactly who is working on what, how much progress has been made, and where bottlenecks exist.

Comparison: Jira vs. GitLab Project Management

3. Key Fields of a GitLab Issue

To ensure clear ownership and execution, every GitLab issue contains several key metadata fields:

1. Title: A concise, action-oriented summary of what needs to be accomplished (e.g., Implement login API with JWT authentication).
2. Description: A detailed markdown-supported text area outlining requirements, steps to reproduce, acceptance criteria, or technical designs.
3. Assignee: The specific team member responsible for executing the task. This establishes clear ownership.
4. Labels: Tags used to categorize, prioritize, and route the issue through the workflow.
5. Milestone: The target sprint or release cycle to which the issue belongs, establishing a clear deadline.

4. Categorization and Organization with Labels

Without proper categorization, a project's issue tracker quickly becomes cluttered and unmanageable. GitLab uses Labels (which act as metadata tags) to organize, filter, and track issues.

Common Label Taxonomies

• Type Labels: Define the nature of the issue.
  • bug: Code defects that need fixing.
  • feature: New capabilities that need to be developed.
  • enhancement: Optimizations or refactoring of existing code.
• Priority Labels: Establish urgency.
  • high: Critical path items that block releases or affect production.
  • medium: Standard priority tasks.
  • low: Non-blocking improvements or nice-to-have features.
• Status Labels: Track the current phase of execution.
  • to do: Backlog items ready for development.
  • in progress: Tasks currently being worked on by an assignee.
  • done: Completed tasks.

Real-World Filtering

By applying these labels, team leads and developers can instantly filter hundreds of issues down to a specific subset. For example, to find all critical defects currently being worked on, a developer can apply the filter:

5. Time-Bound Goals with Milestones (Sprints)

A Milestone in GitLab represents a time-bound goal. It is the direct equivalent of an Agile Sprint or a release target.

Characteristics of a Milestone

• Start and End Dates: Defines a strict timeline (e.g., a 2-week sprint from May 1st to May 14th).
• Issue Grouping: Collects multiple issues that must be completed within that timeframe.
• Progress Tracking: Provides visual metrics showing the percentage of completed versus open issues.

The completion percentage of a milestone is calculated mathematically based on the state of its assigned issues:

For example, if a milestone contains 3 issues and 1 is closed, the milestone progress is:

6. Visualizing Workflows with Issue Boards (Kanban)

An Issue Board is a visual representation of your project's workflow. Based on the Kanban methodology, it displays issues as cards arranged in vertical lists (columns).

Workflow Movement

Issues move horizontally across the board as their status changes. This movement is controlled dynamically by adding or removing labels.

[ Backlog / Open ]
        |
        | Developer pulls task
        v
    [ To Do ]
        |
        | Developer starts coding
        v
 [ In Progress ]
        |
        | Code is merged & verified
        v
    [ Done ]

Benefits of Issue Boards

• Visual Tracking: Instantly see which tasks are stuck, which are in progress, and who is working on what.
• Team Alignment: Prevents team members from being overloaded by visualizing work-in-progress (WIP) limits.
• Quick Status Checks: Stakeholders can assess project health at a glance without reading individual status reports.

7. Managing Large Initiatives with Epics

When planning large-scale software projects, individual tasks (issues) are often part of a much larger strategic initiative. GitLab uses Epics to manage these high-level goals.

Note: Epics are an advanced planning feature and are available only in GitLab Premium and Ultimate tiers.

Concept and Structure

An Epic represents a large feature or project that cannot be completed in a single sprint. It acts as a parent container that groups multiple related issues.

By grouping issues under an Epic, product managers can track the overall progress of a major release while developers work on smaller, bite-sized tasks.

8. Step-by-Step Hands-On Guide: Creating and Organizing Issues

This section walks through the practical implementation of Agile planning inside a GitLab project.

Step 8.1: Create Project Issues

1. Navigate to your GitLab project repository.
2. In the left sidebar, go to Plan -> Work items (or Issues).
3. Click on New item (or New issue).
4. Create three distinct issues with the following details:

Issue 1: Implement Login API

• Title: Implement login API with JWT authentication
• Description: Develop a secure REST endpoint for user authentication. The endpoint must validate credentials and return a JSON Web Token (JWT) with a 24-hour expiration.
• Click Create issue.

Issue 2: Fix Login Bug

• Title: Fix login bug
• Description: Users are experiencing intermittent 500 Internal Server Errors when attempting to log in with special characters in their passwords.
• Click Create issue.

Issue 3: Add Logout Feature

• Title: Add logout feature
• Description: Implement a logout endpoint that invalidates the user's active JWT session on the server side.
• Click Create issue.

Step 8.2: Create Project Labels

To organize these issues, we must define our project's label taxonomy.

1. In the left sidebar, navigate to Manage -> Labels.
2. Click New label.
3. Create the following labels:

Step 8.3: Assign Labels to Issues

Now, map the labels to their respective issues to categorize them.

1. Go back to Plan -> Work items.
2. Open Issue 1 (Implement login API with JWT authentication).
3. In the right-hand sidebar, locate the Labels section and click Edit.
4. Select the feature label.
5. Open Issue 2 (Fix login bug).
6. Assign the bug and high priority labels.
7. Open Issue 3 (Add logout feature).
8. Assign the feature label.

Step 8.4: Create and Assign a Milestone (Sprint 1)

Next, we will group these issues into a time-bound sprint.

1. In the left sidebar, navigate to Plan -> Milestones.
2. Click New milestone.
3. Configure the milestone:
   • Title: Sprint 1
   • Start Date: Select today's date.
   • Due Date: Select a date 7 to 14 days in the future.
4. Click Create milestone.
5. To assign issues to this milestone:
   • Go to Plan -> Work items.
   • Open each of the three issues.
   • In the right sidebar, locate Milestone, click Edit, and select Sprint 1.

9. Step-by-Step Hands-On Guide: Configuring Custom Issue Boards

With issues, labels, and milestones established, we can now build a custom Kanban board to manage our workflow visually.

Step 9.1: Create a Custom Board

1. In the left sidebar, navigate to Plan -> Issue boards.
2. By default, GitLab provides a basic board with Open and Closed columns.
3. Click the dropdown arrow next to the board name and select Create new board.
4. Name the board Sprint 1 Board.
5. Click Create board.

Step 9.2: Configure Custom Lists (Columns)

We want our board columns to map directly to our status labels (to do, in progress, done).

1. Click Configure board (or use the Create list button).
2. Select Label as the list type.
3. Choose the to do label and click Add to board.
4. Repeat this process to add lists for in progress and done.
5. Drag and drop the columns to arrange them in logical sequence:

Step 9.3: Move Issues Through the Board

1. Open Issue 3 (Add logout feature) and assign the in progress label.
2. Open Issue 2 (Fix login bug) and assign the in progress label.
3. Open Issue 1 (Implement login API with JWT authentication) and assign the done label.
4. Go back to your Sprint 1 Board. You will see the issues automatically categorized into their respective columns based on their active labels.
5. Open Issue 1 directly from the board, add a comment: "Task is completed successfully.", and click Comment and close.
6. Observe that the issue moves to the Closed status.

10. Advanced Workflow: Automating Issue Closure via Merge Requests

One of the most powerful features of GitLab's integrated DevOps platform is the ability to link issues directly to Git branches and Merge Requests (MRs). By using specific keywords in your commit messages or MR descriptions, you can automate your workflow.

The "Closes" Keyword

When a Merge Request containing the text closes #<issue_number> is merged into the default branch (e.g., main), GitLab automatically:

1. Closes the specified issue.
2. Removes active status labels (like in progress).
3. Updates the associated Milestone progress metrics.

Step-by-Step Automation Walkthrough

1. Clone the Repository and Create a Branch

Open your local terminal and run the following commands to clone your repository, switch to the main branch, pull the latest changes, and create a new feature branch:

# Clone the repository (replace with your project's SSH/HTTPS URL)
git clone git@gitlab.com:your-username/your-project.git
cd your-project

# Ensure you are on the main branch and have the latest code
git checkout main
git pull origin main

# Create and switch to a new feature branch
git checkout -b feature/login-bug

2. Make Code Changes and Commit

Simulate fixing the bug by modifying a file, then commit the changes:

# Create or modify a file to simulate a bug fix
echo "Fixing password special character validation" >> auth.py

# Stage and commit the changes
git add auth.py
git commit -m "fix: resolve login authentication bug with special characters"

# Push the branch to GitLab
git push origin feature/login-bug

3. Create a Merge Request with Closing Keywords

1. Navigate to your GitLab project in the browser.
2. You will see a prompt to Create merge request for your recently pushed branch feature/login-bug. Click it.
3. In the Description field of the Merge Request, use the closing keywords to reference the open issues. For example, if your "Fix login bug" issue is #2 and your "Add logout feature" issue is #3, write:

This merge request resolves the authentication issues identified in Sprint 1.

closes #2
closes #3

4. Click Create merge request.

4. Merge and Verify

1. Click Approve (if approval rules are configured) and then click Merge.
2. Once the pipeline completes and the branch is successfully merged into main, navigate to Plan -> Milestones -> Sprint 1.
3. Observe that the milestone progress now shows 3/3 complete (100%).
4. All three issues have been automatically closed and moved to the completed state without any manual intervention in the ticketing UI.

11. Summary and Key Takeaways

• GitLab Issues serve as the foundational unit of work, replacing external ticketing systems like Jira to reduce context switching and licensing costs.
• Labels act as highly customizable metadata tags categorized by Type (bug, feature), Priority (high, medium), and Status (to do, in progress).
• Milestones represent time-bound goals equivalent to Agile Sprints, allowing teams to track progress against strict start and end dates.
• Issue Boards provide a visual Kanban interface where dragging and dropping cards dynamically updates their associated labels and statuses.
• Epics (available in Premium/Ultimate) allow product managers to group multiple related issues under large, strategic initiatives.
• GitLab's Closing Keywords (e.g., closes #ID) in Merge Requests automate the development lifecycle by closing issues and updating milestone metrics the moment code is merged.