appendix i github projects

Appendix I: GitHub Projects Deep Dive

Listen to Episode 26: GitHub Projects Deep Dive - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

Boards, Tables, Roadmaps, Automations, and Accessible Navigation

GitHub Projects is GitHub's built-in project management system. It connects issues and pull requests from one or more repositories into a living, filterable view that your whole team can see and act on. This appendix covers everything beyond the basics introduced in Chapter 08: Labels, Milestones, and Projects.

Table of Contents

1. Projects v2: What Changed
2. Creating a Project
3. The Three Layouts in Depth
4. Custom Fields
5. Adding and Managing Items
6. Built-In Automations
7. Iterations (Sprints)
8. Views and Filters
9. Cross-Repository Projects
10. Screen Reader Navigation Reference
11. Accessibility Agents: /project-status
12. Exercises

1. Projects v2: What Changed

GitHub has two generations of project tooling. The current generation - called Projects (v2) - is what you'll find on any repository or organization page today.

Layouts: Classic v1 offered Kanban board only. V2 offers Board, Table, and Roadmap.

Custom fields: Classic v1 had none. V2 supports Text, Number, Date, Single Select, and Iteration fields.

Automations: Classic v1 had no built-in automations. V2 has native GitHub Actions integration.

Cross-repo support: Classic v1 did not support cross-repository tracking. V2 does.

Filtering: Classic v1 had limited filtering. V2 supports full field, label, assignee, and status queries.

API: Classic v1 had a limited API. V2 has full GraphQL support.

If you see "Projects (Beta)" references in older documentation, those referred to the early rollout of v2. It is now stable and the default.

2. Creating a Project

Projects can be created at the organization level (shared across all repos in an org) or at the repository level (scoped to one repo).

Create from an Organization

1. Navigate to your organization page (github.com/your-org)
2. Select the Projects tab
3. Activate "New project" button
4. Choose a template (blank table, blank board, feature release, etc.) or start empty
5. Give the project a name and select "Create project"

Create from a Repository

1. Navigate to any repository
2. Select the Projects tab
3. Activate "Link a project" or "New project"
4. Follow the same template/name flow

Screen Reader: Project Creation

1. Navigate to org or repo Projects tab
   → Tab to the green "New project" button → Enter
2. Template modal opens
   → Arrow keys to browse template cards
   → Enter to select a template
3. Name field: type your project name
4. "Create project" button: Tab → Enter
5. You land on the new empty project

3. The Three Layouts in Depth

Table View

The default layout. A spreadsheet-style grid where each row is an issue, PR, or draft item. Columns are fields (Title, Status, Assignee, Labels, Priority, custom fields you create).

What it's best for: Bulk editing, sorting, filtering, seeing many items at once with their field values.

Keyboard navigation

T                     → Jump to table
↑/↓                   → Move between rows
←/→                   → Move between columns
Enter                 → Open item detail panel (right sidebar)
Escape                → Close detail panel
Space (on a cell)     → Edit that cell's value
F2 (on title cell)    → Edit title inline

Screen reader output per row

"Fix keyboard trap in modal dialog | Status: In Progress | Assignee: alice | Priority: High | Labels: bug, accessibility"

Board View

Kanban-style columns. Each column represents a status value. Cards can be dragged between columns (or updated via keyboard by editing the Status field).

What it's best for: Visual workflow tracking, seeing WIP (work in progress), standup-style status reviews.

Screen reader note: Drag-and-drop is not keyboard accessible. Change a card's column by opening it and editing the Status field instead.

Keyboard navigation

Tab                   → Move between columns and cards
Enter (on a card)     → Open item detail panel
B                     → Jump to board regions (if heading navigation)
Within a card:
  Enter               → Open panel
  Space               → Toggle selection (for bulk moves)

Change a card's column without dragging

1. Enter to open the card
2. Navigate to the Status field in the right panel
3. Activate the Status dropdown
4. Select the new column value
5. Escape to close

Roadmap View

A horizontal timeline. Items appear as bars spanning their start/due dates. Iterations and milestones can be visualized against real calendar time.

What it's best for: Release planning, sprint capacity planning, communicating timelines to stakeholders.

Screen reader note: Roadmap is chart-based. The underlying data is still fully accessible via the Table view - treat Roadmap as a visual summary, and use Table for all editing.

Setting dates

• Add a Date custom field (e.g., "Start Date", "Due Date") or use a Milestone field
• Items without dates appear in the ungrouped section

4. Custom Fields

This is one of Projects v2's most powerful features. You can add fields beyond the GitHub defaults (Title, Assignee, Labels, Milestone, Repository).

Field Types

Text: Free-form notes for things like acceptance criteria or design links.

Number: Numeric values such as story points or estimates (for example, "Points: 3").

Date: Deadlines or start dates (for example, "Due: 2025-06-15").

Single select: A dropdown with predefined options, useful for priority, size, or type fields (for example, Priority: P0, P1, or P2).

Iteration: Sprint or cycle tracking. See Section 7 for details.

Creating a Custom Field

From any project view:

1. In Table view, scroll right to the + button at the end of the column header row
2. Activate the + button
3. Select a field type
4. Name the field and configure options (for select fields, type each option, press Enter to add more)
5. Confirm - the field appears as a new column

Screen reader path

Tab to "+" column header button → Enter
→ Field type menu opens → ↑/↓ to choose type → Enter
→ Name field: type field name
→ For "Single select": type option names, Tab/Enter between options
→ "Save" button → Enter

Editing a Field Value on an Item

1. In Table view, navigate to the cell where the field intersects the row
2. Enter or Space to activate the editor
3. Type value (text/number) or select from dropdown (single select)
4. Enter or Tab to confirm

5. Adding and Managing Items

Add an Existing Issue or PR

From any project view:

1. Activate the "+ Add item" button at the bottom of a table/column
2. Type # to trigger the issue/PR search
3. Type a keyword or issue number
4. Select the item - it's added to the project
5. The issue/PR is now tracked in the project; it still lives in its repository

Tip: The issue itself will now show which projects it belongs to in its sidebar.

Add a Draft Issue

Draft issues live only inside the project (not in any repository) until you promote them.

1. Activate "+ Add item"
2. Type the title directly (no #)
3. Press Enter - a draft row appears
4. Open the draft → "Convert to issue" button → select the repository

When to use drafts: Capturing ideas during planning before you're ready to commit them to a repo.

Promote a Draft to an Issue

1. Open the draft item (Enter on the row)
2. Activate "Convert to issue" in the panel
3. Select the target repository from the dropdown
4. Confirm - the draft becomes a real issue in that repo

Bulk Edit Items

In Table view:

1. Check the checkbox on each row (first column, Space to toggle)
2. A bulk action bar appears at the top
3. Options: change Status, assign label, change assignee, archive, delete

6. Built-In Automations

Projects v2 has native automation rules - no GitHub Actions YAML required.

Accessing Automations

From a project:

1. Select the ... menu (project overflow) in the top-right
2. Select "Workflows"
3. You'll see a list of built-in automation rules you can enable/disable

Available Built-In Workflows

Item added to project: When an item is manually added, its Status is set to a value you choose.

Item reopened: When an issue or pull request is reopened, its Status changes back (for example, to "In Progress").

Item closed: When an issue or pull request is closed, its Status is automatically set to "Done."

Pull request merged: When a pull request is merged, its Status is set to "Done."

Auto-add to project: Items matching a filter (by label, type, or repository) are automatically added to the project.

Setting Up Auto-Add

This is the most powerful workflow for maintainers:

1. In Workflows, select "Auto-add to project"
2. Toggle it On
3. Configure the filter: e.g., label:accessibility is:issue adds any new issue with the accessibility label automatically
4. Save

Now any matching issue in linked repos is added to your project the moment it's filed - no manual triage step required.

GitHub Actions Integration

For more complex automations, Projects v2 has a full GraphQL API and works with GitHub Actions. Example use cases:

• Auto-assign items based on repository when added
• Set due dates based on linked milestone
• Send Slack notifications when high-priority items are added

See Appendix Q: GitHub Actions and Workflows for the foundation, and the GitHub documentation on automating projects for advanced patterns.

7. Iterations (Sprints)

An iteration field lets you group work into time-boxed cycles - sprints, weeks, or any cadence you choose.

Creating an Iteration Field

1. Add a new field (the + column button in Table view)
2. Select "Iteration" as the field type
3. Name it (e.g., "Sprint")
4. Set the iteration duration (1 week, 2 weeks, custom)
5. GitHub automatically generates current and upcoming iterations

Using Iterations

• Each item can be assigned to an iteration via the Iteration field
• In Board view, you can group by iteration to see a sprint board
• In Roadmap view, iterations appear as blocks on the timeline
• Burndown: No built-in burndown chart, but the Insights charts (see below) can show progress

Iteration Insights

From any project:

1. Select the Insights tab (the bar chart icon)
2. Select "Current iteration"
3. See: items by status, completion rate, items added vs closed over time

8. Views and Filters

A view is a saved configuration of layout + filters + grouping + sort. You can have many views on one project, each showing a different slice of the data.

Creating a View

1. Activate the "+ New view" button in the view tab bar
2. Choose layout (Table, Board, Roadmap)
3. Configure filters, grouping, sort
4. The view saves automatically with a default name - rename by clicking/activating the tab label

Filter Syntax

The filter bar accepts a query language similar to GitHub's issue search:

status:In Progress shows only items with that Status value.

assignee:@me shows only items assigned to you.

label:accessibility shows items with the accessibility label.

milestone:"v2.0" shows items in a specific milestone.

no:assignee shows items with no assignee.

is:pr shows only pull requests. is:issue shows only issues.

repo:owner/name shows items from a specific repository, useful in cross-repo projects.

You can combine filters: assignee:@me status:"In Progress" shows your in-progress work.

Grouping

In Table or Board view, you can group rows:

1. Select "Group by" in the view configuration menu
2. Choose any field: Status, Assignee, Priority, Iteration, Label, Repository
3. Items are collapsible into group sections

Sorting

Multiple sort levels are supported. Primary sort → secondary sort:

• Priority ascending, then due date ascending

9. Cross-Repository Projects

A single project can track issues and PRs from multiple repositories - including repos in different organizations (if you have access).

Add a Repository to a Project

1. In project settings (the ... overflow menu → "Settings")
2. Select "Manage access" → "Add repository"
3. Search and select additional repositories
4. Items from those repos can now be added to the project

Using the Repository Field

When a project spans multiple repos, the "Repository" field lets you see - and filter by - which repo each item belongs to:

Filter: repo:community-access/accessibility-agents
→ Show only accessibility-agents issues in this cross-repo project

Common use case: An organization project tracking all accessibility bugs across every repo, labeled accessibility, with Auto-add enabled.

10. Screen Reader Navigation Reference

Project Home Page (list of projects)

3 → Jump to project titles (they are h3 links)
Enter → Open a project

Inside a Project - General

Tab → Move between interactive elements (view tabs, filters, fields, buttons)
F6 → Cycle between major panels (header, view tabs, content area)
/ → Focus the filter bar (if supported; otherwise Tab to reach it)

Table View

T or Region → Jump to the table data region
↑/↓ → Navigate rows
←/→ → Navigate columns within a row
Enter → Open item detail panel
Space → Toggle row selection
Escape → Close detail panel or cancel edit
F2 → Edit a title cell if focused

NVDA note: Use Browse mode (NVDA+Space to toggle) to read all cell content, then App mode (NVDA+Space again) for interactive editing. NVDA announces cell content as you navigate with arrow keys.

JAWS note: Use JAWS cursor (JAWS+P) to read grid cell content. For interactive editing, press Enter to enter application mode in the table.

VoiceOver note: Use VO+Shift+↓ to interact with the table. VO+←/→ moves between cells. Press VO+Space to activate a cell for editing.

Board View

Tab → Move between cards and column headers
Enter (on card) → Open detail panel
The "Status" field in the panel → Change the card's column

Detail Panel (right sidebar, any view)

Tab → Move between fields
Enter/Space → Activate a field editor
Select dropdowns → ↑/↓ to navigate options, Enter to select
Escape → Close the dropdown or the panel

Filter Bar

Click/Tab to filter bar → type query → Enter to apply
Backspace → Remove last filter token
Escape → Clear focus from filter bar

11. Accessibility Agents: /project-status

The /project-status command from Accessibility Agents gives you a live project board overview directly in VS Code Copilot Chat, without opening a browser.

What It Shows

/project-status community-access/accessibility-agents

• Items per column (Todo, In Progress, Done, etc.) with assignees and average age
• Blocked items (labeled "blocked" or flagged with a field value)
• Stale items - in the same column for 7+ days with no activity
• Unassigned items in active columns
• Team member workload (anyone with 5+ items in progress)
• Sprint/iteration progress if an Iteration field is configured

Example Output

GitHub Project: Accessibility Agents Roadmap (3 active views)

Column Breakdown:

Column	Items	Assignees	Avg Age	Stale (7d+)
To Do	8	@alice (3), @bob (2)	5 days	1
In Progress	4	@charlie (2)	3 days	0
In Review	2	--	2 days	0
Done	23	--	--	--

Attention Items:

• Stale: "Update screen reader navigation guide" - In Review for 9 days, no activity
• Unassigned: "Triage accessibility bug backlog" in In Progress

After the overview: "Want to see a specific column or check a team member's workload?"

When to Use It

• During standup: quick status snapshot without leaving VS Code
• Before filing a new issue: see if it's already tracked
• During sprint planning: identify stale and blocked items before the next cycle
• After a weekend: catch up on what moved while you were away

12. Exercises

Exercise 1: Create a Personal Tracking Project

1. Create a new project at the organization level: name it "My Workshop Contributions"
2. Add the Board layout
3. Add a custom Priority field with options: P0, P1, P2
4. Add your fork of accessibility-agents as a linked repository
5. Add any open issue you've filed to the project

Exercise 2: Set Up Automation

1. In your project's Workflows, enable "Item closed" → Status: Done
2. File a test issue in your fork
3. Close that issue
4. Verify it moved to "Done" automatically in the project board

Exercise 3: Create a Sprint View

1. Add an Iteration field named "Sprint" with 2-week iterations
2. Assign your existing project items to the current sprint
3. Switch to Roadmap view - observe the items on the timeline
4. Check Insights to see the current iteration burndown

Exercise 4: Cross-Repo Project (Advanced)

1. Create a cross-repo project connected to two of your repositories
2. Add the Repository field to the Table view
3. Create a view filtered to is:issue label:accessibility
4. Set up Auto-add: any issue with the accessibility label in those repos goes to this project automatically

From Chapter 08: For the introductory coverage of Labels, Milestones, and Projects including screen reader basics for getting started, see Chapter 08: Labels, Milestones, and Projects.

Return to: Resources | Glossary