GitLab for Education – First Assignment Guide

Overview

This guide walks you through every step of setting up your first class assignment in GitLab — from creating the right group structure to inviting students and grading their work. By the end you'll have a repeatable workflow you can reuse each semester.

🗂️

Step 1

Create Your Groups

📝

Step 2

Set Up the Assignment

👥

Step 3

Add Students

✅

Step 4

Review & Grade

🏗️ How It All Fits Together

Here is the complete structure you will build. Each student ends up with their own private space containing a copy of the assignment, while you retain full visibility across all of them.

📁 your-institution (Top-level Group)
   └── 📁 cs101-fall (Course Subgroup)
        ├── 📄 assignment-1-template
        ├── 📁 student-alice
        │    └── 📄 assignment-1
        └── 📁 student-bob
             └── 📄 assignment-1

📋 Before You Start

Your institution's GitLab for Education subscription has been approved and activated.
You have an Owner-level GitLab account linked to your subscription.
You have a list of student GitLab usernames or institutional email addresses.
Your assignment brief and any starter code are ready, or you can use the GitLab Assessment Template Project.

Step 1 of 4

Create Your Course Group & Subgroups

Groups and subgroups are the backbone of your course structure in GitLab. They control who can see and access what, and keep all your course content organised in one place.

📁 Create the Course Subgroup

Each course should have its own subgroup. If you have already set up your GitLab for Education subscription, your institution will have a top-level group — add a subgroup inside it.

Navigate to your top-level group's overview page.
Select New subgroup in the upper-right corner.
Enter the subgroup name — for example, CS101 – Introduction to Programming – Fall.
Set the URL slug to something concise with no spaces — for example, cs101-fall.
Add a short description to help students identify the course.
Set visibility to Private.
Select Create subgroup.

💡

Naming tip Include the course code, name, and semester in the group name, but keep the URL slug short — you'll be typing it frequently.

👤 Create Per-Student Subgroups

Each student needs their own private subgroup within the course subgroup. This is where their individual assignment repositories will live, and ensures students cannot see each other's work.

Navigate into your course subgroup (e.g., cs101-fall).
Select New subgroup.
Name the subgroup after the student — for example, alice-smith.
Set visibility to Private.
Select Create subgroup. Repeat for each student.

ℹ️

Large classes For classes of 30 or more students, consider scripting subgroup creation using the GitLab REST API automation script. This can reduce setup time significantly.

🔑 Your Group Structure at This Point

📁 your-institution ← Top-level group (you are Owner)
   └── 📁 cs101-fall ← Course subgroup
        ├── 📁 alice-smith ← Student subgroup
        ├── 📁 bob-jones ← Student subgroup
        └── 📁 cara-lee ← Student subgroup

✅

Step 1 complete. Your course group and per-student subgroups are ready. Next, you'll create the assignment template project.

Step 2 of 4

Create & Configure the Assignment

You'll create a template project containing the assignment brief and any starter code, then fork it into each student's subgroup so they each have their own private copy to work in.

📄 Create the Assignment Template Project

The template is the master copy of the assignment. Students will never edit this directly — they each get their own fork of it.

Navigate to your course subgroup (e.g., cs101-fall).
Select New project → Create blank project.
Name the project assignment-1-template.
Ensure the namespace is set to your course subgroup, not your personal namespace.
Set visibility to Private.
Check Initialize repository with a README.
Select Create project.

💡

Try the template project You can use the GitLab Assessment Template project if you want to try things out with a ready-made project. Simply fork it into your group and skip to the "Fork the Template" section below.

✏️ Add the Assignment Brief

Edit the README to contain the full assignment brief — objectives, requirements, deliverables, submission instructions, and the deadline.

In the project, select the README.md file and open it for editing.
Replace the default content with your assignment instructions.
Select Commit changes with a message such as Add assignment brief.

⚙️ (Optional) Add a CI/CD Pipeline

A CI/CD pipeline automatically runs your tests every time a student pushes code, giving instant feedback and making grading more objective.

In the template project, select + → New file.
Name the file .gitlab-ci.yml.
Add the pipeline configuration below, adjusting for your language and test framework.
Commit the file.

# .gitlab-ci.yml – Sample Python test pipeline

image: python:3.11

stages:
  - test

run-tests:
  stage: test
  script:
    - pip install pytest
    - pytest tests/ --tb=short
  artifacts:
    when: always
    reports:
      junit: report.xml

ℹ️

Every time a student pushes a commit, GitLab installs dependencies and runs the test suite. A green ✓ or red ✗ badge appears on each commit, giving students instant feedback.

🔀 Fork the Template into Each Student's Subgroup

Navigate to the assignment-1-template project.
Select Fork from the top-right of the project page.
Under Project URL, change the namespace to the student's subgroup (e.g., cs101-fall / alice-smith).
Name the forked project assignment-1.
Select Fork project. Repeat for each student subgroup.

✅

Step 2 complete. Each student now has a private copy of the assignment. Next, you'll add them as members so they can access it.

Step 3 of 4

Add Student Users

With the assignment projects in place, give each student access to their own subgroup and add any TAs or graders at the course level.

📋 Before You Invite

Each student must have a GitLab account before you can add them. Share these instructions with your class ahead of time:

Go to gitlab.com and create a free account (or sign in via institutional SSO if available).
Use your institutional email address when registering.
Send your GitLab username to your instructor before the start of the course.

👤 Add Each Student to Their Subgroup

Add each student to their own subgroup as a Developer — full access to push code within their own space, without being able to see other students' work.

Navigate to the student's subgroup — for example, cs101-fall / alice-smith.
Select Manage → Members from the left sidebar.
Select Invite members.
Enter the student's GitLab username or email address.
Set their role to Developer.
Optional: Set an Access expiration date matching your semester end date.
Select Invite. Repeat for each student.

🧑‍🏫 Add TAs and Graders to the Course Subgroup

Add TAs at the course subgroup level so they have access to all student repositories in one step.

Navigate to the course subgroup — for example, cs101-fall.
Select Manage → Members → Invite members.
Enter the TA or grader's GitLab username.
Assign the appropriate role (see table below).
Set an expiration date to match the end of semester.
Select Invite.

Role	Best for	What they can do
Owner	Course instructor	Full access — manage all settings, view and edit all repos, manage members
Reporter	TAs / Graders	Read and clone all student repositories; leave comments; cannot modify student code
Developer	Senior TAs (trusted)	Can push to repositories and manage CI/CD — use only for trusted staff

💡

Recommended for most TAs: Use Reporter. They can read, clone, and comment on student work without being able to accidentally overwrite it.

ℹ️

Managing a large cohort? Use the automation script to bulk-assign students to subgroups using a CSV class list.

📣 Notify Students

Once students are added, send them:

The URL of their personal assignment repository.
Instructions to clone the repository locally using git clone [repo URL].
The submission method — opening a Merge Request before the deadline.
The deadline and grading criteria (already in the README).
Who to contact if they have access issues.

✅

Step 3 complete. Students and staff now have access to the right repositories. In the final step, you'll learn how to review and grade submissions.

Step 4 of 4

Reviewing & Grading Submissions

When the submission deadline arrives, you have several tools in GitLab to review student work, leave feedback, and record grades.

📬 Receiving Submissions via Merge Request

Navigate to a student's assignment project — for example, cs101-fall / alice-smith / assignment-1.
Select Code → Merge Requests from the left sidebar.
Open the student's submission merge request.
Select the Changes tab to view a line-by-line diff of everything they've written.
Select any line to leave an inline comment with feedback.
Use the Overview tab to leave a general comment summarising your grade and overall feedback.
When done, either Approve the merge request or Request changes if revisions are needed.

💡

Inline comments are one of GitLab's most powerful grading tools. You can point students directly to specific lines of code and explain exactly why marks were awarded or deducted.

⚗️ Reviewing CI/CD Pipeline Results

If you set up the CI/CD pipeline in Step 2, GitLab will have automatically run your test suite on each student's latest commit.

Navigate to the student's project.
Select Build → Pipelines from the left sidebar.
Find the pipeline associated with their final submission commit.
Select the pipeline to view the full job log and test results.
A green ✓ indicates all tests passed; a red ✗ indicates failures.

💡

Time saver For assignments with automated tests, pipeline results can dramatically reduce time assessing correctness — you only need to review code quality and documentation manually.

💬 Leaving Feedback with Issues

For detailed written feedback — or if a student did not submit via Merge Request — use GitLab Issues.

Navigate to the student's project.
Select Plan → Issues → New issue.
Title the issue clearly — for example, Assignment 1 Feedback – Grade: B+.
Write your feedback in the description, using Markdown for structure.
Assign the issue to the student so they receive a notification.
Select Create issue.

📊 Grading Approaches at a Glance

🔀 Merge Request Review

Best for all assignments. Gives line-by-line diff view, inline commenting, and a structured approval workflow.

⚙️ CI/CD Pipeline Results

Best for code correctness. Automated test results are objective, instant, and require no manual running of code.

💻 Local Clone & Run

Best for interactive programs or outputs that can't be tested automatically. Clone, run, return feedback via GitLab.

💬 Issues for Feedback

Best for detailed written feedback. Creates a persistent, visible record for the student to reference.

✅

Guide complete! You've successfully set up a course group, created and distributed an assignment, added your students, and established a grading workflow. This structure can be reused every semester with minimal changes.

Setting Up Your First Teaching Assignment using GitLab