GitHub 13 🌐 Managing Project Boards and GitHub Projects (v2) - KandZ

⏱️ Estimated read: 10 min | |

GitHub Projects (v2) is not a board. It is a database with multiple views. This distinction is the single most important concept to internalize before touching the interface. The classic Projects product—columns of cards, one board per repository—is deprecated and being retired. The modern Projects product stores items as rows in a table, and the board, roadmap, and table layouts are all just different lenses on the same underlying data. Changing an item in one view changes it everywhere, because there is only one dataset .

Key point: A Project is a collection of items (issues, pull requests, and draft issues) with custom fields. Views are saved configurations of layout, filters, grouping, and sorting. One project can span multiple repositories and track work that has not yet become an issue.

Why Projects v2 exists

The classic board problem. Classic Projects was a literal kanban board: columns, cards, and nothing else. It could not track items across repositories, had no custom fields beyond the card itself, and offered minimal automation. GitHub sunset the classic product in favor of a flexible, database-backed system that can represent any workflow, not just a single board .

The cross-repository problem. Modern software work spans multiple repositories. A feature may require changes to a backend, a frontend, and a documentation repo. Projects v2 lives at the user or organization level, not on a single repository. It can pull issues and pull requests from any repository the viewer has access to, and it can contain draft issues that live only inside the project until they are promoted to real issues .

The field problem. Labels and milestones belong to the repository. They are shared across all issues in that repository and cannot be customized per project. Projects v2 introduces custom fields: text, number, date, single-select, and iteration. These fields belong to the project, not the repository. An issue can have a priority/p1 label and a Priority single-select field simultaneously; they are stored in different places and serve different purposes .

The view problem. A single team may need a board for daily standups, a table for backlog grooming, and a roadmap for release planning. Classic Projects forced a choice. Projects v2 allows multiple saved views over the same items. Each view can have its own layout, filters, grouping, and sorting. The data is shared; the presentation is not .

The automation problem. Projects v2 ships with built-in workflows that run without GitHub Actions YAML. The most powerful is “Auto-add to project”: any issue matching a filter (by label, type, or repository) is added to the project automatically. Combined with “Item closed” and “Pull request merged” workflows, the project stays synchronized with repository activity without manual triage .

a. Creating a project and adding items

A project is created from the organization or user profile page. The “New project” button offers a blank project (Table, Board, or Roadmap layout) or a template. The template pre-configures fields, views, and workflows, which is useful for teams adopting a standard workflow .

Items are added in three ways. First, the “Add item” button at the bottom of the table accepts a URL to an issue or pull request. Second, the item’s sidebar on the issue or pull request page shows which projects it belongs to; from there, it can be added to additional projects. Third, the “Auto-add to project” workflow adds items automatically when they match a filter .

A draft issue is an item that exists only inside the project. It has a title and an optional body, but no repository, no issue number, and no assignee until it is promoted. Drafts are useful during planning, before the work is ready to be committed to a repository. The “Convert to issue” button in the item panel moves the draft into a chosen repository, creating a real issue with the draft’s content .

b. Custom fields and views

Out of the box, a project includes a Status single-select field with options Todo, In Progress, and Done. It also displays built-in fields: Title, Assignees, Labels, Milestone, Repository, Reviewers, and Linked pull requests. These built-in fields are read from the repository and cannot be edited in the project; they are views into the underlying issue .

Custom fields extend the project’s data model. The field type determines what kind of questions can be answered. A Number field (e.g., Estimate) can be summed and charted. A Date field (e.g., Target ship) feeds the roadmap layout. A Single-select field (e.g., Priority, Component) is used for grouping and filtering. An Iteration field defines recurring time-boxes (sprints) with a start date and duration; GitHub generates the current and upcoming iterations automatically .

A view is a saved configuration. The “+ New view” button creates a new tab. The layout is chosen first (Table, Board, Roadmap), then filters, grouping, and sorting are applied. The view saves automatically; renaming it makes it distinguishable to the team. A board view groups items by a single-select field (usually Status), turning the rows into columns. A roadmap view uses date fields and iteration fields to plot items on a timeline .

Filters use a query language similar to GitHub’s issue search. status:In Progress shows items in that status. assignee:@me shows the viewer’s items. label:accessibility filters by label. repo:owner/name limits to a specific repository. Filters can be combined, and the resulting view is saved for the team .

c. Built-in workflows and automation

The “Workflows” menu in the project’s overflow menu lists the built-in automations. These are distinct from GitHub Actions; they are native to Projects and require no YAML. The available workflows include: “Item added to project” (set a field value when an item is added), “Item closed” (set Status to Done when an issue closes), “Pull request merged” (set Status to Done when a PR merges), “Item reopened” (set Status when an issue reopens), and “Auto-add to project” (add items matching a filter) .

The “Auto-add” workflow is the most consequential for maintainers. A filter like label:bug is:issue means that any new issue with the bug label in any linked repository is added to the project automatically. The item is not just visible; it triggers the other workflows as if it had been added manually. The project becomes a live view of repository activity, not a manually curated list .

For automations beyond the built-in set, the project exposes a GraphQL API. A GitHub Action can add items, update fields, or query the project’s state. This is the path for complex logic: assigning items based on repository, setting due dates from milestones, or sending notifications to external systems .

Complete Example Session

# ============================================
# PART 1: CREATE A PROJECT
# ============================================

# Navigate to organization or user profile → Projects → New project
# Choose "Board" from the "Start from scratch" options
# Name: "Platform Sprint Board"
# Click "Create project"

# ============================================
# PART 2: ADD A CUSTOM FIELD
# ============================================

# In the Table view, click "+" at the far right
# New field → Name: "Priority"
# Type: Single select
# Options: P0, P1, P2
# Click "Save"

# ============================================
# PART 3: CREATE AN ITERATION FIELD
# ============================================

# New field → Name: "Sprint"
# Type: Iteration
# Duration: 2 weeks
# GitHub generates Sprint 1, Sprint 2, etc.

# ============================================
# PART 4: ADD ITEMS MANUALLY
# ============================================

# Click "+ Add item" at the bottom of the table
# Paste URL: https://github.com/org/repo/issues/42
# Press Enter
# The issue appears as a row.

# ============================================
# PART 5: ADD A DRAFT ISSUE
# ============================================

# Click "+ Add item"
# Type: "Investigate latency regression" (no #)
# Press Enter
# A draft row appears.
# Click the draft → "Convert to issue" → select repo

# ============================================
# PART 6: CONFIGURE AUTO-ADD WORKFLOW
# ============================================

# Project menu (…) → Workflows
# "Auto-add to project" → Edit
# Filter: label:bug is:issue
# Save and turn on
# Any new bug issue is now added automatically.

# ============================================
# PART 7: CREATE A FILTERED VIEW
# ============================================

# Click "+ New view"
# Name: "My P0s"
# Layout: Table
# Filter: assignee:@me priority:P0
# The view shows only the viewer's P0 items.

# ============================================
# PART 8: GROUP A BOARD VIEW
# ============================================

# Create a new view: "Sprint Board"
# Layout: Board
# Group by: Status
# The board shows columns for Todo, In Progress, Done.
# Dragging a card updates the Status field.

# ============================================
# PART 9: VERIFY AUTOMATION
# ============================================

# Create a new issue in any linked repo with label "bug"
# Open the project
# The issue appears automatically with Status = Todo (if configured)

The nine parts trace the Projects v2 lifecycle: creating a project, adding custom fields, defining an iteration cadence, adding items and drafts, configuring auto-add, creating filtered views, grouping a board, and verifying that the automation works.

Quick Reference

Project vs Classic

Aspect	Classic (deprecated)	Projects v2
Core object	Board with columns	Table of items with fields
Views	One board	Many saved views
Custom fields	No	Yes
Scope	One repo	User or org, many repos
Automation	Basic	Built-in workflows + Actions

Custom Field Types

Type	Use For	Example
Number	Estimates, counts	Story points
Date	Deadlines, ship dates	Target ship
Single-select	Fixed categories	Priority, Status
Iteration	Sprints, time-boxes	Sprint

Built-in Workflows

Workflow	Trigger
Item added to project	Set a field value on add
Item closed	Set Status when issue closes
Pull request merged	Set Status when PR merges
Auto-add to project	Add items matching a filter

Best Practices

✅ Do This:

Auto-add filter: label:bug is:issue
<!-- Every bug is tracked without manual triage -->    # ✅

Single-select field for Priority
<!-- Group and filter by priority -->                 # ✅

Iteration field for sprints
<!-- Time-boxed planning with dates -->               # ✅

❌ Don’t Do This:

# Use classic Projects
<!-- Deprecated; no custom fields or cross-repo -->    # ❌

# Track everything in one project
<!-- Scope creep; the project becomes unusable -->    # ❌

# Manually add every issue
<!-- Auto-add eliminates the triage step -->           # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Project scope creep	One project tracks everything	One project per initiative or quarter
Stale items clog views	Closed issues not archived	Enable auto-archive or archive manually
Custom field not visible	Field hidden in view	Click “+” in table header, enable field
Auto-add not working	Filter too narrow or workflow off	Verify filter syntax and toggle state
Draft lost	Not promoted to issue	Open draft → “Convert to issue”

Real-World Examples

1. Create Project

Org → Projects → New project → Board

2. Add Single-Select Field

Field: Priority, Options: P0, P1, P2

3. Add Iteration Field

Field: Sprint, Duration: 2 weeks

4. Add Item by URL

Paste https://github.com/org/repo/issues/42

5. Convert Draft

Draft → "Convert to issue" → select repo

6. Auto-Add Filter

label:bug is:issue

7. Filter View

assignee:@me status:"In Progress"

8. Group Board by Status

Board → Group by → Status

9. Roadmap View

Layout: Roadmap → use Target ship date field

10. Bulk Edit

Table view → select rows → change Status

Visual

Projects v2 Data Model

┌──────────────────────────────────────────────┐
│  PROJECT (database)                          │
│                                              │
│  Fields: Status, Priority, Sprint, Estimate  │
│  Items: Issue #42, PR #43, Draft "Latency"   │
└──────────────────┬───────────────────────────┘
                   │
        ┌──────────┼──────────┐
        │          │          │
        ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│  Table   │ │  Board   │ │  Roadmap │
│  View    │ │  View    │ │  View    │
│          │ │          │ │          │
│  Rows    │ │  Columns │ │  Timeline│
│  + fields│ │  by Status│ │  by date │
└──────────┘ └──────────┘ └──────────┘

The views are lenses. The data is shared.

Auto-Add Workflow

┌──────────────────────────────────────────────┐
│  Issue created in any linked repository      │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Matches filter? label:bug is:issue          │
│  ├─ YES → Add to project automatically       │
│  └─ NO  → Ignore                             │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Item appears in project with default fields │
│  Other workflows may set Status = Todo       │
└──────────────────────────────────────────────┘

Auto-add eliminates the manual triage step.

Summary

Item	Value
Projects v2 type	Database with views
Item sources	Issues, PRs, draft issues
Scope	User or org, many repos
Custom field types	Text, number, date, single-select, iteration
Views	Table, Board, Roadmap
Built-in workflows	Auto-add, item closed, PR merged, item added
GraphQL API	For custom automation
Classic Projects	Deprecated

Key takeaways:

Projects v2 is a database, not a board. The board is one view over a table of items with custom fields .
Custom fields belong to the project, not the repository. A Priority field and a priority/p1 label are different things stored in different places .
One project can span multiple repositories. It lives at the user or org level and can pull items from any linked repo .
Auto-add is the most powerful workflow. It eliminates manual triage by adding matching issues automatically .
Iteration fields enable sprint planning. They generate dated time-boxes that feed board grouping and roadmap views .
Views are saved configurations. Filters, grouping, and sorting are part of the view, not the data. One project can have many views for different audiences .

Remember: A Project is not a list of cards. It is a set of items with fields, and the board is a way of looking at those items. Build the fields first, then the views. Configure auto-add to keep the data current. The project stays synchronized with the repositories, and the team stops spending time on triage.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!