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 8)

Chapter 8 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 8 Guided Challenge: Triage Recommendation Comment

1. Open your assigned challenge issue.
2. Review issue title, description, and target file.
3. Post a triage recommendation comment using this format:

Chapter 8 triage recommendation:
- Suggested labels:
- Suggested milestone:
- Suggested project board column:
- One-sentence reason:

4. If you have write access, apply the recommended labels/milestone directly.

This keeps the task simple and accessible for all students, including those without triage permissions.

Expected Outcomes

• Student can recommend labels/milestone/project placement using issue context.
• Student understands triage even without maintainer permissions.
• Student leaves a clear, reusable triage note for maintainers.

If You Get Stuck

1. Start with one label only (documentation, bug, or accessibility).
2. If milestone is unclear, write none and explain why.
3. If project board is unknown, write needs triage and continue.
4. Ask facilitator to review your one-sentence reason before posting.

Learning Moment

Triage is about clarity, not authority. Good recommendations reduce maintainer effort and speed up collaboration.

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