Teacher Guide

Planning Student Projects with GitLab

A step-by-step guide to using Milestones, Epics, Issues, Labels, and Merge Requests to run structured, trackable projects in the classroom.

Audience: Instructors Covers: Milestones · Epics · Issues · Labels · MR closure
ℹ️
What this guide is for

When students work on multi-week team projects, good planning structure is often as important as the code itself. GitLab's built-in planning tools mirror how agile software teams work in industry — teaching students to use them is as valuable as the project itself.

The Planning Hierarchy

🏁 Milestones

Time-boxed goals with a start and due date. Represent a sprint checkpoint or project phase.

🗺️ Epics

Large themes or feature areas spanning multiple issues. Appear on the Roadmap as a Gantt chart.

📌 Issues

Individual tasks, features, or bugs. The atomic unit of work — assigned, labeled, and linked.

🏷️ Labels

Tags applied to issues and MRs for categorisation — type, priority, and status.

🔀 Merge Requests

The code submission. Linked to issues via closing keywords — merged MRs close linked issues automatically.

📊 Roadmap

A visual Gantt chart of all epics on a timeline. Shows plan distribution across the semester.

📚 Example scenario used throughout this guide

CS301 – Software Engineering Team Project

A team of four students is building a simple web application over 8 weeks. The project has three major feature areas: user authentication, a data dashboard, and an API layer.

This guide uses that project as the running example. By the end you'll have a complete planning structure that works for any team project of similar scope.

1
Start here

Create Milestones — Your Project Timeline

📋 Plan your milestones before creating them

For an 8-week project, a sensible milestone structure mapped to grading checkpoints:

M1 · Project Setup Week 1–2 · Repo, planning, initial issues
M2 · Core Features Week 3–5 · Main development sprint
M3 · Integration & Testing Week 6–7 · Connect components, test
M4 · Final Submission Week 8 · Polish, documentation, demo

➕ Create a milestone

Create milestones at the group level for team projects so they apply across all student subgroups.

  1. Navigate to your course group or the team's project.
  2. In the left sidebar, select Plan → Milestones.
  3. Select New milestone.
  4. Give it a clear title — for example, M2 – Core Features.
  5. Set a Start date and Due date matching your course schedule.
  6. Add a short description of what should be completed by this milestone.
  7. Select Create milestone. Repeat for each checkpoint.
🎓
Teaching moment Ask students to help define the milestones during the project kickoff. Having them set their own deadlines increases buy-in and teaches scope estimation — a skill that takes years to develop professionally.
ℹ️
Milestone dashboard Each milestone has its own page showing a burndown chart, percentage complete, total issue weight, and all linked MRs. This is your primary progress tracking view.
2
Before writing any issues

Set Up Labels — Your Tagging System

Labels let you categorize, filter, and visualise work. Set up your label system before students start writing issues — retrofitting labels later is tedious. Use three categories: type, priority, and status.

🏷️ Recommended label set

Type labels

feature bug infrastructure documentation

Status labels

status::to-do status::in-progress status::in-review status::done

Priority labels

priority::high priority::medium priority::low

➕ Create labels

Create labels at the group level so they are available in all student projects.

  1. Navigate to your course group.
  2. In the left sidebar, select Plan → Labels.
  3. Select New label, enter the name, choose a color, and select Create label.
  4. Repeat for all labels in your set.
💡
Scoped labels The status:: and priority:: prefixes create scoped labels — GitLab enforces that only one label per scope can be applied at a time, preventing issues from being marked both status::to-do and status::in-progress simultaneously.
🎓
Teaching moment The status label system directly models Kanban workflow. Use your issue board (Plan → Issue Boards) with columns named after each status label to give students a visual Kanban view. This is how most software teams manage day-to-day work.
3
High-level structure

Create Epics — Your Feature Areas

🗺️ Plan your epics

For the CS301 example project:

Epic 1 · User Authentication (login, registration, sessions)
Epic 2 · Data Dashboard (charts, filters, data display)
Epic 3 · API Layer (endpoints, data models, testing)
Epic 4 · Documentation & Testing (README, tests, user guide)

➕ Create an epic

Epics are created at the group level, not inside individual projects.

  1. Navigate to your course group.
  2. In the left sidebar, select Plan → Epics.
  3. Select New epic.
  4. Give it a descriptive title and add a description with acceptance criteria.
  5. Set a Start date and Due date (these control how it appears on the Roadmap).
  6. Select Create epic. Repeat for each major feature area.
ℹ️
Dates matter for the roadmap Epics only appear as bars on the Roadmap if they have both a start and a due date set.
4
The unit of work

Write Issues — Individual Tasks

Issues are the atomic unit of work. Each issue should represent a single, completable task — small enough to finish in a day or two, large enough to be meaningful. Require students to write issues before they write code.

✏️ What makes a good issue

A well-written issue includes: a clear, action-oriented title; a description with acceptance criteria ("this is done when..."); an assignee; a label (type + status + priority); a milestone; and a parent epic.

➕ Create an issue

  1. Navigate to the team project.
  2. In the left sidebar, select Plan → Issues → New issue.
  3. Write a clear, action-oriented title.
  4. Add a description with acceptance criteria.
  5. Assign to a team member, add labels, assign to a milestone, and set the parent epic.
  6. Select Create issue.
🎓
Teaching moment Run a "planning session" at the start of each sprint where the whole team writes issues together. This surfaces disagreements about scope early and teaches collaborative estimation.
5
Connecting plan to code

Link Issues to Merge Requests

When a student opens a merge request for their work, they should reference the issue it resolves. GitLab will automatically close the issue when the MR is merged, keeping the plan and the codebase in sync.

🔑 Closing keywords

Include one of these keywords followed by the issue number in the MR title or description:

KeywordEffect
Closes #42Closes the issue when the MR is merged into the default branch
Fixes #42Same as Closes — preferred for bugs
Resolves #42Same as Closes
Implements #42Links the MR to the issue without auto-closing it
💡
Multiple issues A single MR can close multiple issues: Closes #12, #14, #17. All three issues will close when the MR is merged.
6
During the project

Track Progress

With milestones, epics, issues, and labels in place, GitLab gives you several views to track team progress without asking for separate status reports.

📊 Key views to use

  • Milestone page — burndown chart, percentage complete, and all linked issues and MRs. Check this before each grading checkpoint.
  • Epic page — shows child issues and percentage complete for that feature area.
  • Roadmap (Plan → Roadmap) — Gantt view of all epics. Shows at a glance whether the team is on schedule.
  • Issue board (Plan → Issue Boards) — Kanban view with status label columns. Useful for sprint reviews.
🎓
Teaching moment Use the Roadmap during mid-project check-ins. Ask teams to show their roadmap and explain any changes to scope or timeline. This directly teaches project communication — a skill that is often underdeveloped even in experienced developers.
7
Assessment

Grading Workflow

The planning structure you've set up makes grading planning and process — not just the final code — straightforward and objective.

✅ What to assess

  • Issue quality: Are issues well-written with clear acceptance criteria? Are they appropriately sized?
  • Label discipline: Are labels used consistently? Do status labels reflect actual state?
  • Milestone adherence: Were issues completed by the milestone they were assigned to?
  • MR linkage: Do merge requests reference the issues they resolve?
  • Roadmap realism: Did the team update their plan when scope changed, rather than ignoring it?
✅
All of this is visible in GitLab You do not need separate planning documents or status reports. Everything is recorded in the project history and is fully auditable — you can see exactly who created each issue, when labels were changed, and when MRs were linked.
Setup Checklist
  • Group created with course subgroup and student subgroups
  • Milestones created at group level with correct dates
  • Label set created at group level (type, status, priority)
  • Issue board configured with status label columns
  • Epics created with start and due dates set
  • Students have written issues linked to epics and milestones
  • Students understand closing keywords for MRs
  • Roadmap reviewed with team at project kickoff

Official Documentation