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.

Related appendices: Appendix R: Projects Deep Dive | Appendix A: Glossary Authoritative sources: GitHub Docs: About labels | GitHub Docs: About milestones | GitHub Docs: About Projects

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.

Agentic strategy: Labels and issue states are how we wake up agents. In the Day 2 capstone, you can design an agent that only activates when an issue gets a specific label, such as needs-review or accessibility-check.

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

1. Open the Issues tab in your 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]

1. If you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged.
2. 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

Tool Cards: Apply a Label

github.com (browser):

1. Open the issue or PR.
2. In the right sidebar, click the gear icon next to Labels.
3. Select labels from the dropdown, then click outside to apply.

github.dev (web editor): Not available -- labels are managed on the issue/PR page, not in the code editor.

VS Code Desktop (GitHub Pull Requests extension):

1. Open the issue in the GitHub sidebar panel.
2. Click the label area to add or remove labels.

GitHub Desktop: Not directly supported. Use Repository > View on GitHub to manage labels in the browser.

Git CLI / GitHub CLI:

gh issue edit 42 --add-label "accessibility,good first issue"
gh pr edit 15 --add-label "documentation"

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.

Learning Cards: Labels

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.

Learning Cards: Milestones

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.

Learning Cards: Cross-References

GitHub Projects

See also: Appendix R: Projects Deep Dive covers advanced project board configuration, custom fields, and automation.

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

Learning Cards: GitHub Projects

Practical Organization Strategy for the Hackathon

Here is a recommended structure for your 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 Step: Move on to Chapter 10: Notifications to finish Day 1.

Next: Chapter 10: Notifications and Day 1 Close
Back: Chapter 08: Open Source Culture
Related appendices: Appendix R: Projects Deep Dive

Authoritative Sources

Use these official references when you need the current source of truth for facts in this chapter.

• GitHub Docs, home
• GitHub Changelog
• GitHub Projects docs
• Labels docs
• Milestones docs
• About Git
• GitHub flow
• About pull requests
• About issues
• Contributing to a project

Section-Level Source Map

Use this map to verify facts for each major section in this file.

• Organizing Work and Cross-Referencing on GitHub: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• Workshop Recommendation (Chapter 9): GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• Labels: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• Milestones: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• Cross-References: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• GitHub Projects: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• Practical Organization Strategy for the Hackathon: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs
• Try It: Label and Link: GitHub Docs, home, GitHub Changelog, GitHub Projects docs, Labels docs, Milestones docs