GitHub as a Project Management Tool

Plan, conduct, document, and share a master’s thesis

Moritz Mähr

2026-10-16

Today

Time Block You produce
09:00 Approaches and GitHub basics —
09:15 X1 Create the repository Repository, README, visibility check
09:45 X2 Turn requirements into work 2 epics, 6 sub-issues, 1 story
10:25 Break
10:35 X3 Configure the Project Milestones, Project, priorities, dependency
11:20 X4 Complete one documentation task Merged pull request, closed Issue
12:00 Break
12:10 Consolidate and extend Questions, problems, optional X5 or X6
12:45 Transfer and closing reflection One next step for your thesis

The course

  • When: Friday, 16 October 2026, 09:00–13:00
  • Where: Seminarraum F 001, Hörraumgebäude Unitobler
  • Credits: 0.5 ECTS, passed or failed
  • You pass when you attend the full session. No exercise result is required
  • New to GitHub? Keep the cheat sheet open

The core workflow

Teach less, but make what is taught usable.

Step Exercise What it does for the thesis
Repository X1 One shared place for the documentation
Issues X2 Requirements become tasks
Project X3 Organise, prioritise, and track the work
Pull request X4 Document, review, and complete the work

Optional extensions, self-paced: X5 publication, X6 re-planning.

The scenario

A fictional MA thesis in Digital Humanities (Major):

How did the landscape of Swiss periodicals change between 1830 and 1960 by language, place, and subject?

  • 30 synthetic records, no real data
  • Fictional registration 2026-12-01, fictional submission 2027-06-01
  • Public exercise repository; a real thesis starts private

Project-management approaches

course/approaches

Three questions

  1. What is fixed? The order of the work, the process, or the length of a cycle.
  2. How does new work enter the plan? Once, at any time, or at the start of each cycle.
  3. When do you check progress? At a milestone, all the time, or at the end of each cycle.

Three approaches

Approach Fixed Open to change GitHub feature
Phase plan Order and dates of the phases Little Milestones, roadmap
Kanban The workflow states The next task, at any time Board, Status, column limits
Scrum Cycle length and goal The work of the next cycle Iteration field, status updates

Sources: Kanban Guide 2025.5, Scrum Guide 2020.

A hybrid for a thesis

  • Phase plan for the fixed dates: registration and submission become milestones
  • Kanban for the daily work: the board shows what is ready, in progress, in review
  • A Scrum-like rhythm for the review: 15 minutes every week

No approach guarantees quality or a met deadline. It makes the state visible, so that you can decide early.

GitHub basics

course/cheat-sheet

Why version control?

  • A thesis changes for months. Each commit records who changed what, when, and why.
  • Compare two states, undo a mistake, cite the state that you submitted.
  • git keeps the history on your computer. GitHub hosts it and adds Issues, pull requests, and Projects.

flowchart LR
    W["Working folder"] -- "git add" --> S["Staging area"]
    S -- "git commit" --> L["Local repository"]
    L -- "git push" --> G["GitHub"]
    G -- "git pull" --> W

Two routes

Browser Command line
You need A browser git, gh, a terminal, a text editor
A commit Commit changes git add, git commit, git push
Browser only — Project fields, workflows, access, status updates

Both routes change the same repository. Change the route at any step.

Files and plan

Term What it is
Repository The home of one project: files, history, Issues, pull requests
Commit A saved change with a message, an author, and a date
Branch A separate line of work; main holds the agreed version
Pull request A proposal to bring a branch into main, with review
Issue One piece of work: what to do, and is it done?
Sub-issue · label · milestone Part of a larger Issue · a tag · a group with a due date
Project Your plan as a table, a board, or a roadmap
Release A tagged version with notes; not an archive

Template or fork?

  • Template: start your own project. You get the files, not the history. No connection to the original. You do this in X1.
  • Fork: contribute to another person’s project. It stays connected, so you can propose changes back.

Five objects, five questions

Object Answers
Repository Where do files and history live?
Issue What work, and is it done?
Project How does the work fit a plan?
Release Which state has which version?
Deposit Where is it preserved and citable?

A release is not a deposit.

Rules versus plans

  • KSL governs this course, not your thesis
  • Study plan + faculty regulations govern the thesis of one programme
  • Plans (DMP, AI use, milestones) are your decisions

Every rule needs: source · applicability · status · Issue

What GitHub cannot guarantee

  • Quality
  • Deadline compliance
  • Confidentiality
  • Long-term preservation

X1 Create the repository

09:15–09:45 · course/exercises/x1

X1 · Why and how

The template is a starting point. You make it describe your thesis.

  1. Open the template link. Select the owner, the name, and the visibility.
  2. Click Create repository.
  3. Replace the README. Keep the synthetic-data warning.
  4. Read and replace the commit message that Copilot suggests.
  5. Check the visibility in Settings → Danger Zone.

X1 · The template form

The “Create a new repository” form. The template maehr/open-research-data-template is preselected. The Owner and Repository name fields are empty. Visibility is set to Public.

X1 · Read the AI suggestion

The “Commit changes” dialog. Copilot filled in a commit message and an extended description; the description claims sections that the change does not contain. Below, the option “Commit directly to the main branch” is selected.

X1 · A red cross is expected

README.md of the new repository. Next to the commit message “Initial commit” is a red cross for a failed workflow run. On the right of the file toolbar is the pencil icon to edit the file.

X2 Turn requirements into work

09:45–10:25 · course/exercises/x2

X2 · Why

A plan fails when it lists only intentions (“write chapter 2”).

Each Issue names:

  • an output · an owner · acceptance criteria · the evidence · the basis

An epic groups the work for one outcome. A sub-issue has one output. A story names the person who needs the output.

X2 · Steps

  1. Create the labels kind:epic, kind:task, kind:story.
  2. Create the epics E01 and E08.
  3. Derive E01-T1 yourself from requirement R-05 (study plan, Art. 15 Abs. 5).
  4. Compare it with the example backlog.
  5. Create the other five sub-issues from the backlog.
**Output:** … **Owner:** … **Basis:** Rule: <source> (<status>)
**Acceptance criteria**
- [ ] …
**Evidence:** …

X2 · Epic with sub-issues

Issue #1 “E01 Scope the thesis and register it” with the label kind:epic. Below the description is the Sub-issues panel with four sub-issues, E01-T1 to E01-T4, and the button “Create sub-issue”. E01-T3 has a red blocked icon. The sidebar shows the Project with Status Backlog.

Break

10:25–10:35

X3 Configure the Project

10:35–11:20 · course/exercises/x3

X3 · Why

  • A milestone answers: what must be ready by this date?
  • Date fields answer: when do I work on this?
  • A dependency says this waits for that; a sub-issue says this is part of that
  • The fields and views are the same for every thesis: copy them
  • The decisions stay yours: priorities, dates, justifications

X3 · Steps

  1. Create the milestones M1 (2026-12-01), M2 (proposed), M3 (2027-06-01).
  2. Make a copy of the showcase Project.
  3. Link it to your repository. Check the visibility: a copy starts private.
  4. Pair: invite the partner under Manage access.
  5. Add E01 and E08; the sub-issues follow.
  6. Decide the priority and the dates of each sub-issue.
  7. Mark E01-T3 as blocked by E01-T1.

X3 · Make a copy

The dialog “Make a copy” of the showcase Project. It states that views, custom fields, insights, and workflows will be copied, and that issues and pull requests will not be copied. Below are the owner selector, the field “New project name”, and the button “Copy project”.

X3 · Project access is separate

The page “Manage access” in the settings of the copied Project. The box “Who has access” says “Private project”. Below, the section “Invite collaborators” has a search field, the role Write, and the button Invite. The sidebar lists the copied fields Status, Priority, Start date, Target date, and Basis.

X3 · The roadmap

The configured Roadmap view at Quarter zoom. Bars show E01 and its tasks between October and December 2026. A marker line labelled “M1 Registration submitted” stands at the end of November. E01-T3 has a red blocked icon.

X3 · A dependency, not a hierarchy

Issue #4 “E01-T3 Submit the thesis registration to the Dean’s Office”. Below the title are two labels: “Blocked by: E01-T1 Check the registration requirements” and “Parent: E01 Scope the thesis and register it”. The body lists output, owner, the cited rule, a status note, acceptance criteria as checkboxes, and evidence. The sidebar shows milestone M1, due by December 1, 2026.

X4 Complete one documentation task

11:20–12:00 · course/exercises/x4

X4 · Why and how

Closes #3 in a pull request closes Issue #3 when the pull request merges. The Project workflows move the item to In review and then to Done.

  1. Edit the README on a new branch.
  2. Open a pull request with Closes #<E01-T2>.
  3. Review against the acceptance criteria.
  4. Merge. Check that the Issue is closed and the Project shows Done.

A review is a human check against the acceptance criteria.

X4 · The pull request

Pull request #43 “docs: add research question and scope”. It merges one commit from the branch docs/e01-t2-scope into main. The description starts with “Closes #3” and repeats the acceptance criteria as checked boxes. In the sidebar, Copilot is listed as a reviewer.

X4 · Closed by the merge

Issue #3 “E01-T2 Write the research question and scope” is closed. The timeline says “closed this as completed in #43”. The sidebar shows milestone M1 at 25 percent, the parent issue E01 with 1 of 4 sub-issues done, and under Development the pull request and the release tag.

You completed the core workflow

  • A repository holds the documentation and its history
  • Issues turn requirements into tasks
  • A Project organises, prioritises, and tracks them
  • A pull request documents, reviews, and completes the work

Break

12:00–12:10

Consolidate and extend

12:10–12:45

Your choice

  1. Ask a question, or fix a problem in X1–X4.
  2. Finish an open step of X1–X4. The solutions show the expected state.
  3. Core workflow complete? Start an optional extension:
    • X5 Prepare a reusable output: before you publish
    • X6 React to a delay and a restriction: when the plan changes

X5 and X6 do not depend on each other. Continue after the session.

X5 Prepare a reusable output

Optional extension · self-paced · course/exercises/x5

X5 · Five jobs, five places

Job Question Where
Coordination Who does what, by when? Issues and the Project
Storage Where do the working data live? Where your institution allows
Publication What may others see and reuse? Repository, release, Pages, after the rights decision
Backup Can I restore my work after a loss? A second copy outside GitHub
Preservation Will it still exist in ten years? A deposit with a DOI

X5 · Steps

  1. Upload the CSV. Write the data dictionary (closes E08-S1).
  2. Record the rights and access decision (closes E08-T2).
  3. Publish v0.1.0-demo (E08-T3), or a labelled recovery package.
  4. Optional: correct CITATION.cff.

A release adds source archives with every tracked file at the tag. Check the files before you publish.

X5 · The release

The release page “v0.1.0-demo: documented synthetic dataset (demo)”, marked Latest, with the tag v0.1.0-demo. The notes state that the data are synthetic, list the contents, and state that a GitHub release is not long-term preservation.

X6 React to a delay and a restriction

Optional extension · self-paced · course/exercises/x6

X6 · Two events

  1. The archive delivers the scans two weeks late.
  2. The archive restricts the scans of SYN-P021. They must not appear in any public output.

The official submission date does not move. An extension needs a formal decision.

X6 · Choose one option

Option What you do What it costs
A Release 29 records Release without SYN-P021; explain the gap An incomplete release
B Metadata only Release all 30 records, no scans A less useful release
C Find a substitute Ask a second archive; new task and dependency More work, a second risk of delay

Then: change one dependency, check the roadmap, write D-T02, post a status update.

X6 · A good decision record names

  • the options that you considered
  • the decision and the reason
  • the changes: dates and dependencies, with Issue numbers
  • the consequences for M2, the release, and a reuser
  • what did not change: M3, 2027-06-01

X6 · Status update

The private test Project. In the table, E08 is expanded and shows the new tasks E08-T6 “Receive the scans from the fictional archive” and E08-T7 “Exclude the restricted scans of SYN-P021 from public outputs” with a blocked icon. The side panel shows a status update “On track” from 2026-10-19 to 2027-06-01 that explains the delay, the new task, and the unchanged submission date.

After the workshop

course/after

Weekly review: 15 minutes

  1. Move each card on the Board to its true Status.
  2. Finish a card in In progress before you start a new one.
  3. For each Blocked by: wait, ask, or re-plan.
  4. Check the next milestone on the Roadmap.
  5. Close what is done; link the output.
  6. Record decisions in decisions.md.
  7. Post a status update.

Transfer to a private thesis

  1. Template → Private repository
  2. Make a copy of the showcase Project; it starts private
  3. Find the rules of your programme
  4. Keep official dates unconfirmed until you have them in writing
  5. Decide on rights before you publish anything
  6. Private is not automatically safe storage for sensitive data

Closing reflection

Informal, in pairs. Nobody grades it.

  1. Which step of the core workflow will you use for your thesis first?
  2. Which rule applies to your thesis, and where is its source?
  3. What stays private in your thesis, and why?

You pass when you attended the full session.

Links