X3 Configure the Project

10:25–11:05 · 40 minutes

Add three justified milestones, copy and link a preconfigured Project, decide priorities and dates, and record one blocking dependency.

NoteAt a glance

• Time: 40 minutes
• You produce: three milestones with justified dates; a Project, copied from the showcase and linked to your repository; your six sub-issues in it, with the priorities and dates that you chose; and one “blocked by” dependency.
• New terms: Project, milestone, view, field, Project workflow, dependency. All terms are in the cheat sheet.

Why this step

Issues describe the work. A Project shows the work as a plan: what is waiting, what is in progress, and what happens when. A Project belongs to your account, not to the repository. You link it to the repository, and you set its visibility separately. A public repository can have a private Project, and the reverse.

A plan needs time. GitHub offers two different tools for time, and they answer different questions. A milestone groups Issues under one due date in the repository: “What must be ready for the registration?” Date fields in the Project give each Issue a start and a target: “When do I work on this?” The roadmap shows both together. Milestones and the roadmap form a phase plan; the board adds a Kanban view of the daily work (Approaches).

Order matters too. “Submit the registration” cannot start before “Check the registration requirements” ends. This is a dependency (“blocked by”), not a hierarchy. A parent-child relation says “this is part of that”; a dependency says “this waits for that”. Keep the two apart.

The fields and the views are the same for every thesis, so you copy them from the showcase Project. The decisions stay with you: the priorities, the dates, and the justification of each milestone. Milestone dates need a justification. The fictional registration (2026-12-01) and submission (2027-06-01) stand in for official dates of the Dean’s Office; the six months between them follow the DH study plan, Art. 15 Abs. 4. The middle milestone is your own estimate, and you may move it. Never move an official date silently.

Before you start

• You finished X2.

• Open the showcase Project in a second tab.

• Command-line route: open a terminal in the folder projm-thesis. Run gh auth status and check that the token scopes include project. If they do not, run gh auth refresh -s project.

• Command-line route: define the helper issue. It prints the number of an Issue from the start of its title, for example issue E01-T3. The commands on this page use it, so your numbers can differ from the examples. Define it again in each new terminal.

  issue() { gh issue list --state all --limit 100 --json number,title \
    --jq ".[] | select(.title | startswith(\"$1 \")) | .number"; }

Steps

Create the milestones

Browser

1. Click Issues, then Milestones, then New milestone.
2. Type the title M1 Registration submitted and the due date 2026-12-01.
3. In Description, write the justification. The milestones of the example repository show one for each date.
4. Click Create milestone.
5. Repeat for M2 Data documented and validated (2027-03-01, proposed) and M3 Thesis submitted (2027-06-01).
6. Open each sub-issue and set its milestone in the sidebar: E01 tasks → M1, E08-S1 and E08-T2 → M2, E08-T3 → M3.

(1) Fictional-formal date with justification; (2) Proposed date; (3) New milestone. Captured 2026-10-12.

Command line

1. Read the justifications of the example repository. There is one for each date:

   gh api "repos/maehr/projm-example-thesis/milestones?state=all" --jq '.[] | .title + ": " + .description'

2. Create the three milestones. Replace each JUSTIFICATION with your own justification of the date. Type {owner} and {repo} as shown: gh fills in your repository. Keep the time T12:00:00Z: with T00:00:00Z, GitHub stores the day before.

   gh api repos/{owner}/{repo}/milestones --jq .title -f title="M1 Registration submitted" \
     -f due_on=2026-12-01T12:00:00Z -f description="JUSTIFICATION"
   gh api repos/{owner}/{repo}/milestones --jq .title -f title="M2 Data documented and validated" \
     -f due_on=2027-03-01T12:00:00Z -f description="JUSTIFICATION"
   gh api repos/{owner}/{repo}/milestones --jq .title -f title="M3 Thesis submitted" \
     -f due_on=2027-06-01T12:00:00Z -f description="JUSTIFICATION"

3. Set the milestone of each sub-issue. The helper issue finds the number of each Issue.

   gh issue edit $(issue E01-T1) $(issue E01-T2) $(issue E01-T3) --milestone "M1 Registration submitted"
   gh issue edit $(issue E08-S1) $(issue E08-T2) --milestone "M2 Data documented and validated"
   gh issue edit $(issue E08-T3) --milestone "M3 Thesis submitted"

4. Check the result. Each sub-issue shows its milestone:

   gh issue list --json number,title,milestone --jq '.[] | "\(.number) \(.milestone.title) \(.title)"'

Copy the Project

Browser

1. Open the showcase Project.
2. Click … (top right), then Make a copy.
3. Under Owner, select your account.
4. Type the name PROJM thesis plan. Do not select Draft issues.
5. Click Copy project. The copy opens. It has the views, the fields, and the workflows of the showcase, but no Issues.

(1) Make a copy, in the Project menu (…); (2) What the copy keeps, and what it leaves out; (3) Select yourself as the owner; (4) Name the copy; (5) Copy project. Captured 2026-10-12.

Command line

1. Copy the showcase Project into your account:

   gh project copy 11 --source-owner maehr --target-owner @me --title "PROJM thesis plan"

2. Read the address that gh prints. The number at the end is the number of your Project. The commands on this page use 12. Replace 12 with your number.

Link the Project and set its visibility

Browser

1. Open your repository. Click Projects, then Link a project.
2. Select PROJM thesis plan and click Save.
3. Open the Project. Click …, then Settings.
4. Under Danger zone, check Visibility. A copy starts private. Select Public only on the public path.

Command line

1. Link the Project to the repository of the folder. Do not add --owner @me: with it, the command fails.

   gh project link 12

2. On the public path, make the Project public. A copy starts private. On the private path, skip this step.

   gh project edit 12 --owner @me --visibility PUBLIC

Pair: give your partner access

Skip this step if you work alone.

NoteBrowser only

gh has no command for Project access. To open your Project from the terminal, run gh project view 12 --owner @me --web.

1. Open the Project. Click …, then Settings.
2. Click Manage access. Invite your partner with the role Write. Access to the repository does not include access to the Project.

(1) Manage access; (2) A copy starts private; (3) Invite your partner with the role Write; (4) The copied fields. Captured 2026-10-12.

Add the Issues

Browser

1. In the Project table, click + at the bottom (or press Ctrl+Space).
2. Type #, select your repository, and select the epic E01.
3. Repeat for E08.
4. The workflow Auto-add sub-issues to project adds the six sub-issues. New items get the Status Backlog. If a sub-issue is missing, add it the same way.

Command line

1. Add the two epics to the Project. Add one Issue per command.

   gh issue edit $(issue E01) --add-project "PROJM thesis plan"
   gh issue edit $(issue E08) --add-project "PROJM thesis plan"

2. List the items. The workflow Auto-add sub-issues to project adds the six sub-issues with the Status Backlog. The list shows eight Issues:

   gh project item-list 12 --owner @me

3. The workflow runs with a delay. If the list shows fewer than eight Issues, wait one minute and run the command again.

If a sub-issue is still missing, add it as in step 1, for example gh issue edit $(issue E01-T1) --add-project "PROJM thesis plan".

Decide the priorities and the dates

This step is planning, not copying. You decide, and you can explain each value.

NoteBrowser only

gh can set a field value only with the internal IDs of the Project, the item, the field, and the option. Use the browser for this step. To open your Project from the terminal, run gh project view 12 --owner @me --web.

1. For each sub-issue, set Priority (High, Normal, or Low) and Basis (Rule, Practice, or Demo).
2. Set a Start date and a Target date for each sub-issue. Each target date must lie before the due date of its milestone.
3. Let E01-T3 start after the target date of E01-T1. E01-T3 waits for E01-T1.
4. Open milestone M2. Add one sentence to its description: why this date, and what happens if it moves.
5. Compare your values with the Backlog view of the showcase Project. Your values can differ. You must be able to justify them.

Check the workflows

NoteBrowser only

gh has no command for Project workflows.

1. In the Project header, click Workflows.
2. Check that six workflows have a green dot.
3. Check two of them: Pull request linked to issue sets the Status In review, and Item closed sets the Status Done. X4 depends on both.

(1) Six workflows stay on in the copy; (2) A linked pull request sets Status to In review; (3) true. Captured 2026-10-12.

Record the dependency

Browser

1. Open E01-T3 Submit the thesis registration to the Dean's Office.
2. In the sidebar, click the gear icon next to Relationships.
3. Select Mark as blocked by, then select E01-T1. Close the list.
4. Check that the pill “Blocked by: E01-T1” appears under the title.
5. Optional: mark E08-T3 as blocked by E08-T2.

Command line

1. Mark E01-T3 as blocked by E01-T1:

   gh issue edit $(issue E01-T3) --add-blocked-by $(issue E01-T1)

2. Check the result. The line blocked-by shows E01-T1:

   gh issue view $(issue E01-T3)

3. Optional: mark E08-T3 as blocked by E08-T2:

   gh issue edit $(issue E08-T3) --add-blocked-by $(issue E08-T2)

Optional: build a Project yourself

Do this after the workshop, or if the copy fails. It shows how the copied Project works.

NoteBrowser only

gh can create a Project and its fields, but not its views or its workflows.

NoteBuild the fields, views, and workflows by hand

1. In your repository, click Projects, then New project. Select Table and name the Project.
2. In the table header, click + and select New field. Create Priority (single select: High, Normal, Low), Basis (single select: Rule, Practice, Demo), Start date, and Target date (date).
3. Open the settings of the field Status. Set the options to Backlog, Ready, In progress, In review, Done.
4. Rename the first view to Backlog. Click New view, select Board, name it Board, and type -label:kind:epic in the filter.
5. Click New view, select Roadmap, and name it Roadmap. Click Date fields and select Start date and Target date. Click Markers and select Milestone. Set the zoom to Quarter.
6. Click View, then Save view, then Save in the confirmation dialog.
7. Click Workflows. Select Pull request linked to issue, click Edit, and set the value Status: In review. Save the workflow and turn it on.

Change the Status options before you rely on the workflows. A workflow that used a renamed option stops with an error. Open Workflows and select the new option again.

(1) Active default workflows; (2) Errors after the Status options changed. Captured 2026-10-12.

(1) Date fields; (2) Choose Start date; (3) Choose Target date. Captured 2026-10-12.

Expected state

(1) Views; (2) Expand to show sub-issues; (3) Fields as columns. Captured 2026-10-12.

(1) Filter that hides the epics; (2) Status columns; (3) Fields on a card. Captured 2026-10-12.

(1) Markers, date fields, and zoom; (2) Milestone marker M1; (3) Blocked task on the timeline. Captured 2026-10-12.

• Three milestones exist; each has a due date and a justification.
• The Project is linked to the repository and has the visibility you chose.
• Your six sub-issues are in the Project, each with a Priority, a Basis, a Start date, and a Target date.
• Each target date lies before the due date of its milestone.
• The Roadmap shows bars and the milestone markers.
• E01-T3 shows “Blocked by: E01-T1”.

If something goes wrong

Problem	Cause	Recovery
Make a copy is missing.	You are not signed in, or you opened the Project from a phone.	Sign in. Use a desktop browser.
The copy is private, but you chose the public path.	A copy always starts private.	… → Settings → Danger zone → Visibility.
Your partner cannot see the Project.	Repository access does not include Project access.	… → Settings → Manage access → invite the partner with the role Write.
The sub-issues do not appear.	The epic was added before the workflow ran, or the workflow is off.	Add each sub-issue with + and #. Check Workflows.
The Project does not appear in the repository.	It is not linked.	Projects tab → Link a project.
The roadmap shows “Your project needs at least one date or iteration field”.	The view has no date fields selected.	Select the date fields in Date fields.
The view settings are lost after a reload.	The changes were not saved.	Click View → Save view, then Save in the dialog. A blue dot means unsaved changes.
No gear icon next to Relationships.	The page has not finished loading.	Reload the Issue page and wait.
Time runs out.	—	Skip the second dependency and the M2 justification. Add them during X6.
gh reports that the token is missing the scope project.	You signed in without access to Projects.	Run gh auth refresh -s project.
gh project link reports “Could not resolve to a Repository with the name ‘@me/projm-thesis’” or “has different owner from ‘@me’”.	--owner @me failed in each form that was tested with gh 2.102.0.	Run gh project link 12 without flags in the folder projm-thesis.
gh reports “Your attempt to move this item created a temporary conflict”.	GitHub changed the Project at the same time, for example through a workflow.	Run the command again for the Issue that failed.
issue E01-T3 prints nothing, or gh reports “command not found: issue”.	The title does not start with the ID and a space, or the terminal is new.	Check the title with gh issue list. Define the helper again, as in Before you start.
A command fails.	Usually the installation, the sign-in, or the folder.	See Command-line problems, or do the step in the browser.

Alternatives

• Pair: one person copies and links the Project and invites the partner; the other creates the milestones. Decide the priorities and the dates together.
• Private path: keep the copy private. Project visibility does not follow the repository visibility.

Official documentation

• Copying an existing project
• Adding your project to a repository
• Managing visibility of your projects
• Managing access to your projects
• Using the built-in automations
• Creating a project
• Customizing the roadmap layout
• About milestones
• Creating issue dependencies
• gh project, gh issue edit, and REST API for milestones

Next

X4 Complete one documentation task.