Labels, Milestones, and Projects

Listen to Episode 9: Labels, Milestones, and Projects - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

Organizing Work and Cross-Referencing on GitHub

Labels, milestones, and projects are the organizational layer of GitHub. They turn a chaotic list of issues into a structured, navigable, prioritized body of work.

Workshop Recommendation (Chapter 9)

Chapter 9 is a guided triage chapter focused on organization skills.

• Challenge count: 1 guided challenge
• Automation check: none by default
• Evidence: structured issue comment in assigned challenge issue
• Pattern: inspect, classify, explain

Chapter 9 Challenge Set

1. Post a triage recommendation - read an issue, recommend labels/milestone/project placement, and explain your reasoning.

Challenge 9.1 Step-by-Step: Triage Recommendation Comment

Goal: Read the details of a Learning Room issue and post a structured triage recommendation that a maintainer could act on immediately.

Where you are working: your assigned Chapter 9 challenge issue in the learning-room repository on GitHub.com, plus one other open issue you will triage.

1. Open the Issues tab in the learning-room repository.
2. Find any open issue that does not already have labels applied (or pick one your facilitator assigns).
3. Read the issue title and full description carefully. Note:
   • What type of work is it? (documentation fix, bug report, accessibility improvement, new content)
   • How urgent does it seem? (blocking other work, nice-to-have, unclear)
   • Which file or area of the repo does it affect?
4. Open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)").
5. Scroll to the comment box and post a triage recommendation using this format:

Chapter 9 triage recommendation for issue #[number]:
- Suggested labels: [pick 1-3 from: documentation, bug, accessibility, enhancement, good first issue]
- Suggested milestone: [pick one or write "none - reason"]
- Suggested project board column: [To Do, In Progress, or Needs Triage]
- One-sentence reason: [why you chose these categories]

6. If you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged.
7. Activate the Comment button.

Screen reader tip: When browsing available labels, open the Labels page (/labels path on the repo) to see all label names and descriptions. Your screen reader will read each label name and its description text.

You are done when: Your triage recommendation comment appears on your assigned challenge issue with all four fields filled in.

Completing Chapter 9: Submit Your Evidence

Your triage recommendation comment is your evidence. Close your Chapter 9 challenge issue when done. If you also applied labels directly, mention that in your comment.

Expected Outcomes

• Student can read an issue and recommend appropriate labels, milestone, and project placement.
• Student understands triage reasoning even without maintainer permissions.
• Student leaves a clear, reusable triage note that a maintainer could act on immediately.

If You Get Stuck

1. Not sure which label to pick? Start with just one: documentation, bug, or accessibility. You can always add more.
2. Milestone is unclear? Write none and explain why - that is a valid triage decision.
3. Project board is unknown? Write Needs Triage - that is the correct default.
4. Not sure what the issue is about? Re-read the title and first paragraph. If still unclear, that itself is useful triage feedback ("Issue description is unclear - needs more detail").
5. Ask facilitator to review your one-sentence reason before posting.

Learning Moment

Triage is about clarity, not authority. You do not need maintainer permissions to help organize work. A clear recommendation saves maintainers time and speeds up collaboration. This is a skill used daily in open source.

Continue learning: The GitHub Skills course Introduction to Repository Management covers labels, milestones, and contributor settings in an interactive, self-paced format. See Appendix Z for the full catalog.

Learning Pattern Used in This Chapter

1. Inspect an issue carefully before acting (read before you write).
2. Classify work using a consistent vocabulary (labels, milestones).
3. Explain your reasoning in writing (one-sentence justification).
4. Build triage instincts that transfer to any open source project.

Labels

What Are Labels?

Labels are colored tags applied to issues and pull requests. They communicate at a glance what category, priority, or status an item belongs to. When you scan the issue list with your screen reader, labels are announced alongside each issue title.

Labels are announced as: "Label: bug" or "Labels: accessibility, good first issue" depending on how many are applied.

Standard Labels You Will Find in Most Repos

Navigating to the Labels Page

From a repository:

# List all labels with descriptions
gh label list

# List labels in a specific format
gh label list --json name,description

Applying a Label to an Issue or PR

From an open issue or PR:

# Add a label to an issue
gh issue edit 42 --add-label "accessibility"

# Add multiple labels at once
gh issue edit 42 --add-label "bug,good first issue"

# Remove a label
gh issue edit 42 --remove-label "needs triage"

# Add a label to a PR
gh pr edit 42 --add-label "accessibility"

Filtering Issues by Label

# List issues with a specific label
gh issue list --label "accessibility"

# Combine multiple labels
gh issue list --label "accessibility" --label "good first issue"

# Combine with state filter
gh issue list --label "accessibility" --state closed

# Search across labels
gh issue list --search "label:accessibility label:\"good first issue\""

Creating a New Label

If you have write access:

1. Navigate to Issues → Labels page
2. Tab to "New label" button → Enter
3. Fill in: Label name (F for form field), Color (use the color picker or hex code), Description
4. Tab to "Create label" button → Enter

# Create a new label
gh label create "accessibility" --description "Accessibility-related issue" --color "0075ca"

# Create with a specific color
gh label create "in progress" --description "Being actively worked on" --color "e4e669"

Accessibility note for color: Labels have color, but they also have a text name and description - the color is supplementary information. Screen readers announce the label name, not the color, so labels are fully accessible.

Milestones

What Are Milestones?

Milestones group issues and PRs toward a shared goal or deadline. Think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables"). A milestone shows:

• A title and optional description
• An optional due date
• A progress bar (percentage of closed issues vs total)

Navigating to Milestones

From Issues tab:

1. Press K to find the "Milestones" link → Enter
2. You see a list of milestones, each with its title, progress, and due date

Reading a milestone

Each milestone is announced as a heading + progress information:

• "Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20"

Opening a Milestone

1. Press 3 to navigate milestone titles (they are h3 links)
2. Press Enter to open a milestone
3. The milestone detail page shows all issues and PRs belonging to it
4. Navigate the list with 3 (issue titles) or I (list items)

Adding an Issue to a Milestone

# Assign an issue to a milestone
gh issue edit 42 --milestone "Hackathon Day 1"

# Remove from a milestone
gh issue edit 42 --milestone ""

# List issues in a milestone
gh issue list --milestone "Hackathon Day 1"

gh api repos/{owner}/{repo}/milestones -f title="Hackathon Day 1" -f description="Day 1 deliverables"

Creating a Milestone

Requires write access:

1. Navigate to Milestones page
2. Tab to "New milestone" button → Enter
3. Fill in: Title, Description, Due date (optional)
4. Tab to "Create milestone" → Enter

Due date field note: The date field may render as a date picker. You can:

• Type the date in YYYY-MM-DD format directly (most reliable)
• Or use arrow keys to adjust month/day/year if spin buttons are provided
• Or press Space or Enter to open a calendar widget (if your screen reader supports it) and arrow through dates

Screen readers handle date pickers inconsistently - typing the date is most reliable across browsers.

Cross-References

Cross-references are links between issues, PRs, and commits. GitHub automatically renders #42 as a link to issue or PR #42. This creates a web of context so any contributor can trace the history of a decision.

Types of Cross-References

Typing a Cross-Reference

Inside any comment or PR description text area (Focus Mode):

1. Type # - a live-search dropdown appears
2. Continue typing the issue number or title fragment
3. Use ↓ to navigate the dropdown → Enter to select
4. The #42 link is inserted automatically

For @mentions:

1. Type @ followed by a username
2. A dropdown of suggestions appears
3. ↓ to navigate → Enter to select

When the "Closes" Keyword Fires

The Closes #42 keyword must appear in:

• The PR description (body text)
• A commit message pushed to the default branch

It does not fire from comments on the PR. If you write "Closes #42" in a comment, it creates a reference but does not auto-close the issue on merge.

GitHub Projects

What Is a GitHub Project?

GitHub Projects is a built-in project management tool. It can display issues and PRs from across multiple repositories in one view. Projects support three layouts:

Finding a Project

From an organization page or repository:

1. Navigate to the "Projects" tab
2. Press 3 to navigate project titles (they are h3 links)
3. Enter to open a project

Navigating a Project - Table View

Step 1: The main content is a large grid/table
Step 2: T to jump to the table
Step 3: Ctrl+Alt+↓ to navigate rows (each row is an issue or PR)
Step 4: Ctrl+Alt+→ to navigate columns (Title, Status, Priority, etc.)
Step 5: Enter on a row to open the issue/PR detail panel

What is announced per row

"Add keyboard navigation to carousel | Status: In Progress | Assignee: username | Priority: High"

Navigating a Project - Board View

Step 1: Switch to Board view using the view selector button
Step 2: Each column (Todo / In Progress / Done) is a region
Step 3: D to navigate between column landmarks
Step 4: Within a column: 3 to navigate card titles, I for list items
Step 5: Enter on a card to open the issue/PR panel

Adding an Issue to a Project

From an open issue:

1. Navigate to the sidebar "Projects" section (H or 3)
2. Activate the Projects gear button
3. Select the project from the dropdown

Or from within a project:

1. Activate "Add item" button at the bottom of a column/table
2. Type # to search for existing issues
3. Select the issue → it's added to the project

Practical Organization Strategy for the Hackathon

Here is a recommended structure for the learning-room sandbox project:

Labels to create

accessibility      - all a11y-related work
documentation      - docs-only changes
good first issue   - for new contributors
in progress        - being actively worked on
needs review       - PR is open, review needed
blocked            - waiting on something external
help wanted        - community assistance requested

Milestone to create

Name: Hackathon Day 1 Deliverables
Due: [Day 1 date]
Description: All contributions made during Day 1 of the Open Source AT Hackathon

Workflow

1. File an issue → add label + milestone
2. Comment "I'll work on this" → add "in progress" label
3. Make changes → open PR → link to issue
4. PR merged → issue closes automatically → milestone progress updates

Try It: Label and Link

Time: 2 minutes | What you need: Browser, signed in to GitHub

Go to the Learning Room repository and do two things:

1. Add a label to an issue - Open any issue (press G then I, then Enter on an issue title). Press L (in Focus Mode) to open the label picker. Type documentation to filter, then press Enter to apply it. Press Esc to close.
2. Use a cross-reference - Leave a comment on that issue mentioning another issue number: Related to #1 (or any issue number you've seen). Press Ctrl+Enter to submit.

You're done. You just organized work using labels and connected two issues with a cross-reference.

What success feels like: The label now appears on the issue, and your cross-reference is a clickable link that connects the two issues. That's project management on GitHub - and you did it in under two minutes.

Day 2 Amplifier - Accessibility Agents: @issue-tracker with Labels

Apply labels and milestones manually in today's exercises before using any agent. Labels are the language that automation uses to filter, route, and prioritize work. If you have not designed and applied them yourself, you cannot configure them correctly for automated use - and you cannot tell when automation is applying the wrong ones.

Once you have mastered manual organization:

• In VS Code - @issue-tracker find open issues labeled accessibility, severity-high uses the exact label vocabulary you configured today, delivering prioritized cross-repository results with community engagement and release-impact scoring
• In your repo - Accessibility Agents forks carry the label schema in .github/ISSUE_TEMPLATE/; your project's organizational language travels with every clone and does not require manual recreation
• In the cloud - GitHub Agentic Workflows apply labels automatically when issues are opened, routing work into the right milestone and Project view without manual triage on every item - but only if your labels were designed with clear, consistent intent

Labeling today is not overhead. It is configuring the input layer that every agent downstream depends on.

Next: Notifications Back: Culture and Etiquette Related: Working with Issues | Day 1 Agenda