Scope: Current GitHub Projects / Projects v2, not Projects (classic).
Audience: Developers, DevOps engineers, engineering managers, product managers, project administrators, platform teams, and GitHub organization owners.
Last verified: 2026-09-26 against current GitHub documentation.
Learning style: Concept -> Why it matters -> Hands-on steps -> Example -> Operational guidance.

How to Use This Guide

This is both a tutorial and a reference manual. You can read it end-to-end, or jump directly to the section you need.

Basic (1-2): Understand what Projects is and create your first project.
Fundamentals (3-5): Learn items, fields, and GitHub metadata.
Essentials (6-13): Master views, tables, boards, roadmaps, filters, iterations, and status tracking.
Intermediate (14-28): Add workflows, insights, templates, permissions, documentation, linking, and planning patterns.
Advanced (29-59): Automate with Actions, APIs and CLI; design organization-scale operating models; secure and govern Projects.
Complete Reference (60): Use the final feature map as a revision/checklist page.

Running Example Used Throughout

Imagine an organization named acme-corp with three repositories:

acme-corp/web
acme-corp/api
acme-corp/infra

The organization creates one organization-level project:

Acme Platform Delivery

Recommended starter fields:

Field	Type	Example values	Purpose
Status	Single select	Todo, In Progress, In Review, Done	Workflow state
Priority	Single select	P0, P1, P2, P3	Business/technical priority
Sprint	Iteration	Sprint 24, Sprint 25	Time-boxed planning
Estimate	Number	1, 2, 3, 5, 8	Capacity planning
Team	Single select	Web, API, Platform	Ownership
Start date	Date	2026-10-01	Roadmap start
Target date	Date	2026-10-15	Roadmap target
Release	Text or single select	2026.10	Release grouping

The Mental Model

flowchart LR
    A[Repositories] --> B[Issues and Pull Requests]
    B --> C[GitHub Project]
    D[Draft Issues] --> C
    C --> E[Fields]
    C --> F[Views]
    C --> G[Workflows]
    C --> H[Insights]
    F --> I[Table]
    F --> J[Board]
    F --> K[Roadmap]
    G --> L[Built-in Automation]
    G --> M[Actions and APIs]

The key idea is simple: Projects does not replace issues and pull requests. It organizes and enriches them for planning.

Part I — BASIC

1. BASIC — GitHub Projects Foundations

1.1 Introduction to GitHub Projects

GitHub Projects is GitHub’s flexible planning and work-tracking system. A project can contain issues, pull requests, and draft issues, then add planning metadata and multiple views without duplicating the underlying work.

A useful way to distinguish GitHub’s planning primitives is:

Tool	Primary purpose	Best use
Issue	Track a unit of work, problem, request, or decision	Bug, feature, task, incident action
Pull request	Review and merge code changes	Implementation and review
Milestone	Group issues/PRs toward a repository-level target	Release or phase
Project	Plan and visualize many work items with fields/views	Backlog, sprint, roadmap, portfolio
Project update	Communicate project-level health	Executive/status communication

Projects vs Issues

An issue represents work. A project represents a planning context around work.

One issue can appear in multiple projects. Each project can add its own project-scoped field values. This is useful when, for example, the engineering project tracks Sprint while a company-wide project tracks Strategic initiative.

Projects vs Pull Requests

Pull requests are code-review objects. Projects can include PRs directly and can also expose PR-related metadata such as reviewers and linked pull requests. A mature delivery project often tracks both the issue describing the work and the PR implementing it.

Projects vs Milestones

Milestones are comparatively lightweight and repository-oriented. Projects are richer and can span repositories. Use milestones for a release grouping when that model fits; use Projects for multidimensional planning, custom fields, multiple layouts, charts, and automation.

Projects vs Projects (classic)

This guide covers current Projects, historically called Projects v2. Avoid learning workflows that depend on classic project-board columns/cards. Current Projects is field-driven: the same underlying data can be rendered as a table, board, or roadmap.

Common Planning Use Cases

Use case	Recommended view/model
Product backlog	Table grouped/sorted by Priority
Sprint planning	Iteration field + Board
Kanban	Board using Status as columns
Product roadmap	Roadmap using date/iteration fields
Cross-repository delivery	Organization project + Repository field
Team capacity	Iteration + Estimate + Team/Assignee grouping
Executive overview	Roadmap + project updates + insights
Release tracking	Milestone/Release field + filtered saved view

1.2 GitHub Projects Core Concepts

Concept	Meaning
Project	Planning container owned by a user or organization
Project item	A row/card/timeline item inside the project
Issue	Repository work item
Pull request	Repository code-change/review item
Draft issue	Project-local idea that can later become an issue
Field	Metadata exposed in the project
Custom field	Project-defined text/number/date/single-select/iteration metadata
GitHub metadata	Native data such as Assignees, Labels, Milestone, Repository
View	Saved presentation/configuration of project data
Table	Spreadsheet-style layout
Board	Column/card layout
Roadmap	Timeline layout
Workflow	Automation that reacts to project/item events
Insight	Chart based on project data
Template	Reusable project configuration
Project update	Project-level health/date/message update
Access	Read/write/admin permissions
Visibility	Public or private discoverability

Important Principle: Data vs View

flowchart TD
    A[Project Data] --> B[Items]
    A --> C[Fields]
    B --> D[Saved View 1: Backlog Table]
    B --> E[Saved View 2: Sprint Board]
    B --> F[Saved View 3: Roadmap]
    C --> D
    C --> E
    C --> F

A view does not normally create a second copy of the work. It is another lens over the same project items and fields.

1.3 Project Ownership

Projects can be owned by a personal account or an organization.

User-Owned Projects

Useful for personal planning, prototypes, individual work, or repositories owned by your personal account.

Organization-Owned Projects

Best for shared engineering/product work because they support organization collaboration, teams, organization templates, base permissions, cross-repository planning, and governance.

Recommendation

For company/team work, prefer organization-owned projects unless there is a specific reason to use a personal project.

1.4 Finding Projects

Projects can surface from several places:

Your profile’s Projects page.
An organization’s Projects page.
A repository’s Projects tab when a project is linked/defaulted there.
A team’s Projects page when linked to the team.
Project search/discovery pages and recent-project navigation.
Direct project URLs.

For an organization-level project, a typical URL is:

https://github.com/orgs/acme-corp/projects/12

The final number (12) is the project number, which is different from the GraphQL node ID.

2. BASIC — Creating Projects

2.1 Project Creation

You can start with a blank Table, Board, or Roadmap, or use a template.

Organization Project — UI Flow

flowchart LR
    A[Open Organization] --> B[Projects]
    B --> C[New project]
    C --> D{Choose source}
    D -->|Blank| E[Table / Board / Roadmap]
    D -->|Template| F[Built-in / Org / Recommended]
    E --> G[Name project]
    F --> G
    G --> H[Optional repository import]
    H --> I[Create project]

Practical Steps

Open the GitHub organization.
Select Projects.
Click New project.
Choose Table, Board, Roadmap, or a template.
Give the project a clear name, for example Acme Platform Delivery.
Optionally import items from a repository.
Create the project.
Open project Settings and add a short description and README.

Good Naming Pattern

<team/product> — <planning purpose>

Examples:

Platform — Delivery
Mobile — Q4 Roadmap
Security — Remediation Program
Payments — Sprint Planning

Description vs README

Description: one-sentence purpose.
README: operating instructions and conventions.

Example project README:

## Purpose
Track delivery work across web, API, and infrastructure.

## Working agreements
- Every delivery item must have Status and Priority.
- Sprint is assigned only after planning commitment.
- P0/P1 items require an owner.
- Done items are automatically archived after the retention period.

## Views
- Backlog: prioritized uncommitted work
- Current Sprint: execution board
- Roadmap: delivery timeline
- Risks: P0/P1 work not Done

2.2 Project Creation Sources

Source	When to use
Blank Table	Start data-first; best default for setup
Blank Board	Team already thinks in workflow columns
Blank Roadmap	Timeline is the primary need
Built-in template	Fast start for common planning patterns
Organization template	Standardized internal workflow
Recommended template	Organization-curated preferred starting point
Existing project copy	Reuse a proven configuration
Import from repository	Seed the project with existing issues/PRs

When importing items from a repository during project creation, GitHub can designate that repository as the project’s default repository. A default repository makes issue creation from the project faster because the destination repo is preselected.

2.3 Copying Projects

Copying a project is useful for repeated releases, programs, client engagements, or team setups.

A copied project can carry forward configuration such as:

Views.
Custom fields.
Draft issues and their field values if selected.
Configured workflows, except auto-add workflows.
Insights/charts.

It does not simply clone all original work items and access relationships. Treat a copy as configuration reuse, not as a full project backup.

Copy vs Template

Need	Prefer
One-off clone of a working setup	Copy project
Organization-wide standard	Organization template
Curated creation experience	Recommended template
Versioned operating standard	Maintained template + documented change process

Part II — FUNDAMENTALS

3. FUNDAMENTALS — Project Items

3.1 Item Types

Projects work with three main item types:

Issues — real repository work items.
Pull requests — code changes/reviews.
Draft issues — project-local ideas/notes that can later be converted.

Choosing the Right Item Type

Situation	Use
Work must be discussed, assigned, linked, searched in a repo	Issue
Code change is the planning object	Pull request
Idea is not ready for a repository yet	Draft issue
Backlog brainstorming session	Draft issue first, convert later

3.2 Adding Items

You can add work in several ways.

A. Search from the Project

In the project’s add-item row, type # and choose a repository, then search for an issue or PR.

B. Paste a URL

Paste an issue/PR URL into the add-item row:

https://github.com/acme-corp/api/issues/418

C. Add from Repository

Use Add item from repository, select multiple items, and add them in bulk.

D. Add from the Repository Issue/PR List

Select several issues or PRs -> Projects -> choose the destination project.

E. Add from Inside an Issue or PR

Open the issue/PR -> Projects in the sidebar -> select the project -> optionally populate project fields.

F. Command Palette

On macOS:

Command + K

On Windows/Linux:

Ctrl + K

Search for Add items.

G. Automatic Addition

Configure the built-in Auto-add to project workflow. We cover this deeply in Chapter 15.

3.3 Draft Issues

Draft issues are excellent for planning workshops because they let you capture an idea without immediately choosing a repository.

Example draft:

Title: Add regional failover runbook
Body: Define RTO/RPO, traffic cutover, database recovery, and rollback steps.

Typical lifecycle:

flowchart LR
    A[Idea] --> B[Draft Issue]
    B --> C[Refine title/body]
    C --> D[Assign project fields]
    D --> E{Ready for engineering?}
    E -->|No| C
    E -->|Yes| F[Convert to Issue]
    F --> G[Choose repository]

When converting a draft issue, choose the repository that should own the resulting issue. After conversion, the item becomes a normal GitHub issue while staying represented in the project.

3.4 Creating Issues from Projects

Projects can create repository issues without leaving the planning context.

Click the add control at the bottom of a table/group/board column.
Choose Create new issue.
Select the destination repository.
Enter title/body and available metadata.
Create the issue.

A useful behavior: when creating an issue inside a grouped view, the group’s value can be applied automatically. For example, creating in the In Progress group can prepopulate the project’s Status as In Progress.

3.5 Editing Items

Projects is designed for high-volume editing.

Inline Editing

Click field cells directly and change values.

Bulk Editing

Select multiple rows/cards, then apply a shared field value or action.

Drag-and-Drop Editing

When grouped by a field, dragging an item to another group changes that field value.

Example:

Group by: Priority
Move issue from P2 group -> P1 group
Result: Priority becomes P1

This makes the view itself an editing interface.

3.6 Archiving Items

Archive removes an item from normal project views while preserving its project context and custom-field data. Delete/remove permanently removes the project item from the project.

Action	Still visible in project views?	Recoverable?	Field context retained?
Archive	No	Yes, restore	Yes
Restore	Yes	N/A	Yes
Delete/remove item	No	No project restoration	No project membership
Close underlying issue	Depends on view/filter	Issue can be reopened	Project item remains unless archived/removed

Use archiving as routine cleanup; reserve deletion for mistakes, duplicates, or true removal.

4. FUNDAMENTALS — Project Fields

4.1 Field Fundamentals

Fields add structured planning metadata to project items.

There are two broad classes:

GitHub-provided metadata such as Assignees, Labels, Milestone, Repository, Type, Parent issue, Reviewers.
Custom project fields you create for your planning model.

Current project custom-field types covered here are:

Text.
Number.
Date.
Single select.
Iteration.

Field Design Rule

Create a field only when you plan to filter, sort, group, slice, aggregate, automate, or report on it. If it is merely explanatory prose, it may belong in the issue body instead.

4.2 Text Fields

Text fields hold free-form metadata.

Good uses:

External ticket ID.
Release train identifier.
Customer/account reference.
Short planning note.

Bad uses:

Priority (single select is better).
Estimate (number is better).
Target date (date is better).

Example:

Field: External ID
Value: INC-2026-00491

4.3 Number Fields

Number fields support numeric planning and aggregation.

Examples:

Estimate = 5
Cost = 1200
Risk score = 8
Expected hours = 16

Useful capabilities include numeric filtering and field sums.

Example filters:

estimate:>=5
estimate:1..3
estimate:*..8

Use one estimation scale consistently. Mixing hours and story points in the same field destroys the meaning of totals.

4.4 Date Fields

Date fields enable deadline and roadmap behavior.

Typical fields:

Start date
Target date
Due date
Release date

Example filters:

target-date:@today
target-date:>=@today
target-date:@today..@today+7

Avoid creating several fields that mean almost the same thing. Define exactly what each date means in the README.

4.5 Single-Select Fields

Single-select fields are excellent for taxonomies.

Example Priority:

Option	Meaning
P0	Immediate / critical
P1	High priority
P2	Normal planned work
P3	Lower priority / opportunistic

Other common fields:

Team.
Severity.
Workstream.
Product area.
Release readiness.

Single-select options can have names, colors, and descriptions. The description should define semantics, not restate the label.

4.6 Iteration Fields

Iteration fields represent repeating planning intervals such as sprints.

Example:

Sprint 24: 2026-09-21 to 2026-10-04
Sprint 25: 2026-10-05 to 2026-10-18

You configure:

Start date.
Duration in days or weeks.
Naming.
Future iterations.
Optional breaks.

Relative filters make iteration fields especially powerful:

sprint:@previous
sprint:@current
sprint:@next
sprint:@current..@current+3

Why Iteration Is Better Than a Free-Text Sprint Field

An iteration understands chronology. GitHub can reason about previous/current/next and display iterations on roadmaps. A text field cannot.

4.7 Managing Custom Fields

Typical field lifecycle:

flowchart LR
    A[Need identified] --> B[Choose field type]
    B --> C[Create field]
    C --> D[Define semantics]
    D --> E[Use in views/workflows]
    E --> F[Review usage]
    F --> G{Still useful?}
    G -->|Yes| E
    G -->|No| H[Remove/Delete carefully]

Before renaming or deleting a field:

Check saved views.
Check automation/API scripts.
Check charts.
Check team documentation.
Check whether a similar organization-level issue field should replace it.

5. FUNDAMENTALS — GitHub Metadata Fields

5.1 Issue and Pull Request Metadata

Projects can display native GitHub metadata such as:

Title.
Assignees.
Labels.
Milestone.
Repository.
Status (project field).
Issue/PR state.

Understand the difference between native metadata and project metadata. A repository label is attached to the issue itself; a project custom field is normally scoped to that project.

5.2 Issue Type

Organizations can use issue types to classify issues. GitHub provides default types such as:

Bug
Task
Feature

Organizations can customize issue types. The project can expose a Type field and use it in views/filters.

Example:

type:bug status:"In Progress"

Use issue types for stable semantic categories; do not recreate Bug, Task, and Feature as ordinary project single-select values unless you have a specific migration reason.

5.3 Parent and Sub-Issue Fields

GitHub issue hierarchy can be exposed in Projects through:

Parent issue.
Sub-issue progress.

Example filter:

parent-issue:acme-corp/api#418

This is useful for work breakdown:

flowchart TD
    A[Initiative Issue] --> B[Feature Issue]
    A --> C[Feature Issue]
    B --> D[Task]
    B --> E[Task]
    C --> F[Task]

Do not invent hierarchy purely with text prefixes like [EPIC]. Prefer real parent/sub-issue relationships plus issue types where possible.

5.4 Pull Request Fields

Useful PR-related fields include:

Linked pull requests.
Reviewers.
Pull request state.
Merge/closed status through native PR state.

A delivery view can therefore show:

Issue -> Linked PR -> Reviewer -> Status

This is valuable for identifying work that is “implemented but waiting for review.”

5.5 Organization-Level Issue Fields

Organization-level issue fields provide structured metadata that lives on the issue and remains consistent across projects in the organization. Current issue-field types include text, number, date, and single-select.

This is different from a project custom field:

Characteristic	Organization issue field	Project custom field
Scope	Organization issues	One project
Value follows issue across projects	Yes	No
Good for shared Priority/Effort	Yes	Sometimes
Applies to PRs	No	Project fields can apply to project items generally
Governance owner	Organization	Project admins

Example Architecture

Use organization issue fields for metadata that should be globally consistent:

Priority
Effort
Start date
Target date

Use project-only fields for planning context that legitimately differs by project:

Program wave
Portfolio lane
Local delivery confidence

Avoid having two fields named Priority with different meanings.

Part III — ESSENTIALS

6. ESSENTIALS — Project Views

6.1 View Fundamentals

A project can have multiple saved views. Each view can have its own:

Layout.
Filter.
Sort.
Grouping.
Slicing.
Visible fields.
Board column configuration.
Roadmap dates/markers.

Example view set:

View	Layout	Purpose
Backlog	Table	Prioritize uncommitted work
Current Sprint	Board	Daily execution
My Work	Table	Personal workload
Roadmap	Roadmap	Timeline planning
Risks	Table	High-risk incomplete work
Done	Table	Recently completed work

6.2 Managing Views

Common actions:

Create.
Duplicate.
Rename.
Save changes.
Reorder tabs.
Delete.
Share the view URL.

Saved vs Unsaved Changes

When you change a saved view’s filter/sort/grouping, GitHub may mark the view as modified. Save the changes if the configuration should become the shared default.

A useful discipline is:

Exploration = do not save
Team convention = save

6.3 Switching Layouts

The same project view can use:

Table — dense editing/analysis.
Board — workflow/card movement.
Roadmap — timeline/date planning.

Each saved view is independently configured. You do not need separate projects just to get separate layouts.

7. ESSENTIALS — Table Layout

7.1 Table Fundamentals

The table is the best place to configure and edit structured project data because it exposes rows and columns directly.

Use it for:

Backlog grooming.
Bulk metadata cleanup.
Planning workshops.
Capacity analysis.
Audit/review of fields.

7.2 Table Customization

You can show/hide and reorder fields to make each table fit its audience.

Engineering table example:

Title | Status | Assignees | Priority | Sprint | Estimate | Linked PRs

Leadership table example:

Title | Status | Team | Priority | Target date | Milestone

The underlying project remains the same; only the visible representation changes.

7.3 Table Organization

Group

Example:

Group by: Priority

This creates sections such as P0, P1, P2, P3.

Sort

Example:

Sort 1: Priority ascending
Sort 2: Target date ascending

Slice

Slicing opens a value selector that lets you quickly focus on one value at a time, such as Team or Sprint, without permanently rebuilding the view.

Field Sums

For a numeric Estimate field, show sums per group to see capacity.

Example:

Sprint 24
  API: 22 points
  Web: 18 points
  Platform: 13 points

7.4 Table Editing

Dragging an item between groups updates the grouped field. Bulk selection makes table layout especially effective for backlog normalization.

Example cleanup workflow:

Filter no:priority.
Select related items.
Bulk-set Priority.
Filter no:assignee.
Assign owners.
Save a Triage view if this is a recurring process.

8. ESSENTIALS — Board Layout

8.1 Board Fundamentals

Board layout represents items as cards arranged into columns.

Common Kanban board:

Todo -> In Progress -> In Review -> Done

flowchart LR
    A[Todo] --> B[In Progress]
    B --> C[In Review]
    C --> D[Done]

8.2 Board Column Fields

A board’s columns can be based on an appropriate field such as:

Status.
Single-select field.
Iteration field.

That means a board does not have to represent workflow state. It can represent releases, teams, or iterations.

8.3 Board Configuration

Useful controls:

Choose the column field.
Show/hide columns.
Reorder cards.
Move one or multiple cards.
Show selected fields on cards.
Group horizontally for a swimlane-like effect.

Example:

Columns: Status
Horizontal group: Team

This creates a team-by-status operating board.

8.4 Board Limits

You can set a column item limit as a work-in-progress signal.

Important: the limit is informational, not a hard enforcement mechanism. Users and automation can still add cards beyond the limit; the UI highlights that the limit has been exceeded.

Example:

In Progress limit = 5
Current count = 8  -> operational warning

8.5 Board Organization

You can combine:

Filter.
Sort.
Slice.
Horizontal grouping.
Field sums.
Item counts.

Example sprint board:

Filter: sprint:@current
Columns: Status
Group by: Team
Field sum: Estimate

8.6 Board Field Updates

Dragging cards is not merely visual. When the board is driven by Status, Iteration, or another supported column field, moving the card updates that field.

This lets teams operate directly from the board during standups.

9. ESSENTIALS — Roadmap Layout

9.1 Roadmap Fundamentals

Roadmap layout places project items on a timeline using date or iteration fields.

Use it for:

Product roadmap.
Release planning.
Program sequencing.
Team delivery windows.
Quarterly/annual visualization.

9.2 Roadmap Dates

Choose the date or iteration fields used for start and target placement.

Example:

Start date field: Start date
Target date field: Target date

Dragging an item on the timeline can adjust these values, turning roadmap planning into an interactive editing process.

9.3 Timeline Controls

Common zoom levels:

Month.
Quarter.
Year.

Use month for delivery planning, quarter for product/program planning, and year for portfolio-level communication.

9.4 Roadmap Markers

Markers can highlight important boundaries such as:

Iterations.
Milestones.
Dates associated with items.

Markers should represent shared reference points, not every minor date; too many markers make the roadmap unreadable.

9.5 Roadmap Organization

Roadmap supports filtering, sorting, grouping, slicing, counts, and number-field sums.

Example portfolio roadmap:

Group by: Team
Filter: -status:Done
Zoom: Quarter
Markers: Milestones

10. ESSENTIALS — Filtering

Filtering is one of the most important GitHub Projects skills because good saved views are mostly good filters plus a suitable layout.

10.1 Project Filters

Basic field filter:

status:Done

Multiple fields use logical AND:

label:bug status:"In Progress"

Multiple values for the same field can act like OR:

label:bug,support

Negation uses -:

-status:Done

10.2 Value Filters

Has a value:

has:assignee
has:priority

Missing a value:

no:assignee
no:priority

Require a value using negation of no::

-no:priority

10.3 Item Filters

Examples:

is:issue
is:pr
is:draft
is:open
is:closed
is:merged
is:issue is:open

Close reason examples:

reason:completed
reason:"not planned"
reason:reopened

Updated-time examples:

updated:@today
updated:@today-1d
updated:>@today-1w
-updated:@today

10.4 Repository Filters

repo:acme-corp/api

For cross-repository projects, repository filters are foundational for team-specific views.

10.5 People Filters

assignee:octocat
assignee:@me
reviewers:octocat
-reviewers:@me

10.6 Number Filters

estimate:>5
estimate:>=5
estimate:<8
estimate:<=8
estimate:1..5
estimate:*..8

10.7 Date Filters

target-date:2026-10-15
target-date:>=2026-10-01
target-date:@today
target-date:@today..@today+7

10.8 Iteration Filters

sprint:@previous
sprint:@current
sprint:@next
sprint:<@current
sprint:@current..@current+3

10.9 Text Filters

Exact field text:

note:"ready for release"

General text search across titles/text fields:

API

Wildcard examples:

title:API*
label:*bug*

10.10 Relationship Filters

Issue type:

type:bug

Parent issue:

parent-issue:acme-corp/api#418

Filter Recipes

Goal	Filter
My open work	`assignee:@me is:open`
Current sprint	`sprint:@current`
Current sprint bugs	`sprint:@current type:bug`
Missing triage	`no:assignee no:priority`
API backlog	`repo:acme-corp/api -status:Done`
High priority incomplete	`priority:P0,P1 -status:Done`
Upcoming week	`target-date:@today..@today+7 -status:Done`
Children of epic	`parent-issue:acme-corp/api#418`

A Useful Constraint

Projects supports OR-like matching for multiple values of the same field, but do not assume arbitrary cross-field Boolean expressions behave like a full query language. Design saved views around supported project filter semantics.

11. ESSENTIALS — Sorting, Grouping and Slicing

11.1 Sorting

Sort is about order.

Examples:

Priority ascending
Target date ascending
Estimate descending

Use multi-field sorting when the secondary sort adds real meaning.

Example:

1. Priority
2. Target date

11.2 Grouping

Grouping creates visual sections.

Good grouping fields:

Status.
Priority.
Team.
Repository.
Iteration.
Assignee.

Dragging between groups can update the grouped value.

11.3 Slicing

Slicing is an interactive focus mechanism. It is useful when you want a single saved view but need to switch rapidly between Team, Sprint, or Priority values.

Think of it as:

Filter = permanently reduce the dataset for the view
Group = partition visible items
Slice = temporarily focus on one field value

11.4 Field Aggregation

Number fields can be summed, and views can expose item counts.

Example capacity table:

Team	Items	Estimate sum
API	9	22
Web	7	18
Platform	5	13

Treat sums as indicators, not truth, unless the team uses a consistent estimation system.

12. ESSENTIALS — Iteration and Sprint Management

12.1 Iteration Planning

A clean sprint model usually needs only:

Sprint (Iteration)
Estimate (Number)
Status (Single select)
Assignee/Team

Planning flow:

flowchart LR
    A[Prioritized Backlog] --> B[Select Sprint]
    B --> C[Estimate Work]
    C --> D[Check Capacity]
    D --> E[Commit Sprint]
    E --> F[Execute on Board]
    F --> G[Review Done/Carryover]

12.2 Iteration Configuration

Configure:

Sprint duration, for example 2 weeks.
Start date.
Iteration naming.
Breaks such as company shutdown weeks.
Future iterations.

If cadence changes, review saved views and planning conventions so teams do not silently interpret iterations differently.

12.3 Iteration Views

Recommended saved views:

Current Sprint: sprint:@current
Next Sprint: sprint:@next
Past Sprint: sprint:@previous
Future Planning: sprint:>@current

Use Board for execution and Table for planning/review.

12.4 Sprint Capacity

A simple capacity model:

Capacity = target estimate points per team per sprint
Committed = sum(Estimate where Sprint=current)
Remaining = Capacity - Committed

GitHub Projects can calculate the committed sum through field sums; your team provides the capacity rule.

Do not use capacity totals to compare engineers. Story points are a planning tool, not a productivity score.

13. ESSENTIALS — Status and Workflow Tracking

13.1 Status Fields

Typical Status taxonomy:

Todo
In Progress
In Review
Done

A minimal taxonomy is usually better than 12 subtle states. Every status should answer a clear operational question.

Example definitions:

Status	Definition
Todo	Accepted into planning but work has not started
In Progress	Active implementation/investigation
In Review	Awaiting code/design/QA review
Done	Team’s definition of done is satisfied

13.2 Workflow State

GitHub objects also have native states:

Issue: open / closed / reopened
Pull request: open / closed / merged / reopened

These are not the same as your project Status field.

13.3 Project State vs Issue State

Example:

Issue state: Open
Project Status: In Review

That is perfectly valid. In Review is a planning state; the issue remains open until completion.

Built-in project workflows can synchronize selected transitions such as:

Issue closed -> Status = Done
PR merged -> Status = Done

The next chapters cover these automations.

Part IV — INTERMEDIATE

14. INTERMEDIATE — Built-In Project Workflows

GitHub Projects includes built-in workflows that handle common synchronization tasks without requiring GitHub Actions or API code.

14.1 Workflow Management

Open a project -> project menu -> Workflows.

For each built-in workflow you can typically:

Inspect its trigger/condition.
Configure the action.
Enable or disable it.
Save and turn it on.

Two useful built-in behaviors are commonly enabled when a project is initialized:

Closed issues/PRs can set project Status to Done.
Merged pull requests can set project Status to Done.

Built-In First, Custom Automation Second

Use this decision rule:

flowchart TD
    A[Automation requirement] --> B{Built-in workflow handles it?}
    B -->|Yes| C[Use built-in workflow]
    B -->|No| D{Needs repository event logic?}
    D -->|Yes| E[GitHub Actions]
    D -->|No| F{Needs system integration or scale?}
    F -->|Yes| G[API / GitHub App]
    F -->|No| H[CLI / manual operation]

Built-in automation is easier to maintain because it does not introduce credentials, workflow files, or custom code.

14.2 Item Added Workflow

Typical rule:

When: Issue or pull request is added to project
Set: Status = Todo

This prevents newly added items from having no status.

A good pattern is to reserve Todo for accepted work. If your project also contains raw intake, consider an Inbox or Triage status instead.

14.3 Item Closed Workflow

Typical synchronization:

Issue/PR closed -> Status = Done

Be careful with issues closed as not planned. Your reporting model may want to distinguish completed work from canceled/rejected work instead of mapping everything to Done.

14.4 Pull Request Merged Workflow

Common behavior:

PR merged -> Status = Done

This is useful when pull requests are direct project items. If your project primarily tracks issues and PRs are only linked metadata, the issue’s completion rule may be more important.

14.5 Item Reopened Workflow

Reopened issues or PRs can be mapped back to an active status according to your team’s workflow.

Example:

Issue reopened -> Status = Todo

If reopening usually means regression/rework, you might choose a dedicated status such as Reopened only if it provides ongoing value. Avoid adding status values for rare edge cases.

14.6 Status-to-Issue Automation

Projects can also drive native issue state in supported workflows, for example:

Project Status becomes Done -> close issue
Project Status moves out of Done -> reopen issue

Use bidirectional synchronization carefully. Decide which system is authoritative:

If engineers close issues in repository workflows, let issue state drive project status.
If project operators control completion centrally, status-to-issue synchronization can fit.

Avoid automation loops where multiple systems repeatedly overwrite each other.

15. INTERMEDIATE — Automatic Item Addition

15.1 Auto-Add Workflow

The built-in Auto-add to project workflow adds new or updated repository items when they match configured criteria.

Example requirement:

Automatically add any open bug from acme-corp/api.

Example filter:

is:issue is:open label:bug

Important Behavior

When you enable auto-add, matching existing items are not necessarily backfilled merely because they already match. The workflow is designed to react as items are created or updated. Use bulk add/import when you need an initial backfill.

15.2 Auto-Add Configuration

Typical steps:

Open the project.
Open Workflows.
Select Auto-add to project.
Click Edit.
Choose the repository.
Enter the filter.
Save and enable the workflow.

The auto-add filter supports a subset of the full project filter syntax. Common supported qualifiers include:

is:
label:
reason:
assignee:
no:

Example recipes:

is:issue is:open label:roadmap
is:pr label:needs-review
is:issue -label:wontfix
is:issue no:assignee

Plan Limits

The maximum number of auto-add workflows is plan-dependent. Treat this as a constrained resource. Prefer broad, understandable workflows over dozens of nearly identical rules.

15.3 Auto-Add Management

You can duplicate an auto-add workflow and point the copy at another repository or filter.

Example cross-repository design:

Workflow 1: acme-corp/web   -> label:delivery
Workflow 2: acme-corp/api   -> label:delivery
Workflow 3: acme-corp/infra -> label:delivery

When your project spans many repositories, GitHub Actions or an App may scale better than maintaining many per-repository built-in auto-add rules.

16. INTERMEDIATE — Automatic Archiving

16.1 Auto-Archive Workflow

Auto-archive keeps active views focused by archiving items that meet selected criteria.

A practical retention rule might be:

is:closed updated:<@today-30d

or a policy based on merged/closed items and age.

The auto-archive workflow supports a restricted filter set, including item state/close reason and updated-time criteria.

Why Archive Instead of Delete?

Archive preserves project field context and allows restoration. This is ideal for normal completion cleanup.

16.2 Archive Management

A healthy project lifecycle is:

flowchart LR
    A[Active] --> B[Done]
    B --> C[Retention Window]
    C --> D[Archived]
    D --> E{Needed again?}
    E -->|Yes| F[Restore]
    E -->|No| G[Remain archived]

Use manual/bulk archive for one-time cleanup and automatic archiving for steady-state hygiene.

17. INTERMEDIATE — Project Insights

17.1 Insights Fundamentals

Insights turns project data into charts. It is useful for operational visibility, workload distribution, status composition, and progress communication.

A chart is only as reliable as the fields behind it. If half your issues have no Priority, a Priority chart is incomplete by design.

17.2 Creating Charts

Typical flow:

Open project Insights.
Create a new chart.
Name it clearly.
Apply a chart filter if needed.
Configure layout/axes/grouping.
Save changes.

Example chart names:

Current Sprint by Status
Open P0/P1 by Team
Estimate by Team
Work by Repository

17.3 Chart Configuration

Common controls include:

Layout/chart type.
X-axis field.
Optional Group by field.
Y-axis aggregation when number fields are used.
Filter.

Example:

Filter: sprint:@current
X-axis: Status
Group by: Team
Y-axis: Sum of Estimate

17.4 Numeric Aggregations

For number fields, supported chart calculations can include:

Count.
Sum.
Average.
Minimum.
Maximum.

Use Count for item volume and Sum for additive metrics such as estimates. Be cautious with averages of story points; they often say little about delivery health.

17.5 Insight Use Cases

Question	Example chart
Where is work stuck?	Count by Status
Which priorities dominate?	Count by Priority
Is sprint load balanced?	Sum Estimate grouped by Team
Which repo carries most work?	Count by Repository
Who is overloaded?	Count/Sum by Assignee, interpreted carefully
Is the roadmap risk-heavy?	P0/P1 incomplete by Target date

Insights is a lightweight project reporting layer, not a replacement for a full analytics warehouse when you need historical cycle-time, lead-time, or complex cross-project BI.

18. INTERMEDIATE — Project Templates

18.1 Built-In Templates

GitHub provides templates for common project patterns. Use them when they are close to your desired operating model and then simplify them if needed.

A template should reduce setup cost, not force a team into fields it does not understand.

18.2 Organization Templates

Organization templates let you standardize:

Fields.
Views.
Draft issues.
Configured workflows, with auto-add exceptions.
Insights.

A project admin can mark an organization-owned project as a template, subject to organization permissions.

Template Example

Engineering Delivery Template
  Views:
    - Triage
    - Backlog
    - Current Sprint
    - Roadmap
  Fields:
    - Status
    - Priority
    - Sprint
    - Estimate
    - Team
  Workflows:
    - Set Todo when added
    - Set Done when closed
    - Set Done when PR merged
  Insights:
    - Sprint by Status
    - Estimate by Team

18.3 Recommended Templates

Organization owners can curate a limited set of recommended templates so users see preferred standards first during project creation.

Use recommendations for officially supported operating models, not every experimental template.

18.4 Template Lifecycle

Treat a template like a product:

flowchart LR
    A[Design] --> B[Pilot]
    B --> C[Publish template]
    C --> D[Teams adopt]
    D --> E[Collect feedback]
    E --> F[Revise standard]
    F --> C

Because existing projects do not magically inherit every later template change, document version changes and provide a migration path for material field/status changes.

19. INTERMEDIATE — Project Updates

19.1 Status Updates

Project updates communicate high-level state separately from individual item status.

A project update can include:

Project health/status.
Start date.
Target date.
Markdown message.

Example update:

### Weekly update
API migration is on track. Web rollout moved by three days because browser regression testing found two P1 issues.

- API: complete
- Web: 80%
- Infra: complete
- Decision needed: approve phased rollout by Friday

19.2 Project Health

Typical health statuses include concepts such as:

On track
At risk
Off track
Complete
Inactive

Define the criteria in your project README. For example:

Health	Internal definition example
On track	Current plan remains achievable
At risk	Material risk exists but recovery plan is plausible
Off track	Target cannot be met without replan/scope/date change
Complete	Project objective is completed
Inactive	Work intentionally paused/not currently active

19.3 Update History

Project updates form a history of project-level communication. Stakeholders with appropriate access can review the latest update and prior updates, and can subscribe to updates.

Use updates for decision-quality summaries, not as a duplicate of the board.

19.4 Project-Level Planning Dates

Project start/target dates describe the overall project. Item-level date fields describe individual work items. Keep these concepts separate.

20. INTERMEDIATE — Project README and Documentation

Every serious shared project should explain how to use it.

Documentation Rule

If a new team member cannot explain the difference between Priority, Severity, Status, and Type after reading the README, the metadata model is under-documented.

21. INTERMEDIATE — Project Visibility

21.1 Visibility Types

Projects can be:

Private — visible only to people with sufficient project access.
Public — visible on the internet.

Critical Security Detail

Public project visibility does not grant repository access. If a project references items from a private repository, viewers who lack repository permission cannot see the private content simply because the project itself is public.

However, project-level metadata and structure can still reveal planning information. Treat public visibility as a deliberate publishing decision.

21.2 Visibility Management

Project admins/organization owners can control visibility according to organization policy.

Before changing a project to public, review:

Project title/README.
Custom field names and values.
Status updates.
Linked repository information.
Draft issues.
Strategic dates.
Customer/product codenames.

22. INTERMEDIATE — Project Access and Permissions

22.1 Permission Levels

Organization projects commonly work with these roles:

Role	Capability summary
No access	No direct project access through base role
Read	View the project
Write	View and edit project content
Admin	Edit and manage project settings/access

Repository permissions still matter. Project access does not automatically grant access to private repository items.

22.2 Organization Access

An organization project can use a base role for organization members and then add team or individual access.

Example model:

Base role: Read
engineering-team: Write
product-team: Write
project-admins: Admin
outside collaborators: Explicit only

This is usually safer and easier to maintain than granting individuals ad hoc write access one by one.

22.3 User Project Access

User-owned projects can invite collaborators and grant project roles, but do not provide the same organization governance model as organization-owned projects.

22.4 Permission Administration

Use least privilege:

Stakeholder who only needs visibility -> Read.
Contributor who manages items/fields -> Write.
Small set of project maintainers -> Admin.

Do not grant Admin merely because someone needs to move cards.

23. INTERMEDIATE — Linking Projects

23.1 Repository Linking

Linking a project to a repository makes it discoverable from that repository’s Projects tab.

Only relevant projects owned by the same user/organization can be linked in this way.

Default Repository

A project can have a default repository. New issues created from the project can then default to that repository.

Use this when one repository owns most work. For a truly balanced multi-repository project, be careful that the default does not cause accidental issue creation in the wrong repo.

23.2 Team Linking

Linking a project to a team improves discoverability and can grant team project access according to GitHub’s team-link behavior.

A team page then becomes a useful entry point for:

Team -> Projects -> Delivery project -> Saved views

23.3 Cross-Repository Planning

An organization project can combine work from many repositories.

Example:

flowchart TD
    A[Acme Platform Delivery] --> B[web issues/PRs]
    A --> C[api issues/PRs]
    A --> D[infra issues/PRs]
    A --> E[shared roadmap]
    A --> F[shared sprint view]

Use the Repository field as a natural dimension for filtering/grouping and reporting.

24. INTERMEDIATE — Project Lifecycle Management

A project itself has a lifecycle.

Typical states/actions:

Create -> Active -> Close -> Reopen (if needed) -> Delete (rare)

Close vs Delete

Close when the project is no longer active but should remain available as historical context.
Delete only when the project is disposable, erroneous, or deliberately being permanently removed.

End-of-Project Checklist

Post final project update.
Mark overall health/status complete as appropriate.
Archive or retain finished items according to policy.
Export data if required for records.
Remove unnecessary automation credentials/workflows.
Close the project.
Keep documentation readable for future audit/reference.

25. INTERMEDIATE — Exporting Project Data

Current GitHub Projects view export downloads TSV (tab-separated values) data.

Typical flow:

Project view -> View menu -> Export view data

Why the Distinction Matters

Many tutorials casually say “CSV export,” but the current GitHub UI exports a .tsv view. Most spreadsheet/data tools can open TSV directly or convert it to CSV.

Example shell conversion:

python - <<'PY'
import csv

with open('project.tsv', newline='', encoding='utf-8') as src, \
     open('project.csv', 'w', newline='', encoding='utf-8') as dst:
    reader = csv.reader(src, delimiter='\t')
    writer = csv.writer(dst)
    writer.writerows(reader)
PY

Export Use Cases

Offline analysis.
Audit snapshots.
Ad-hoc reporting.
Spreadsheet sharing.
Loading project data into a BI/data pipeline.

Remember that exported data is a snapshot, not a live integration.

26. INTERMEDIATE — Project Command Palette

The project command palette speeds up keyboard-driven operations.

Open it with:

macOS: Command + K
Windows/Linux: Ctrl + K

Examples of tasks you can discover/launch from the palette include:

Add items.
Filter-related actions.
View operations.
Field/item operations exposed by the current UI.

Do not memorize every command. Memorize the launcher and search by intent.

27. INTERMEDIATE — Keyboard and Productivity Features

High-throughput project management depends on reducing repetitive clicks.

Useful patterns include:

Inline editing.
Multi-select.
Bulk edits.
Drag-and-drop.
Command palette.
Quick item creation.
Saved views.
Direct view URLs.

Multi-Select Mindset

Instead of editing 30 items individually:

Filter -> Select matching rows -> Bulk update -> Verify

For example:

Filter: sprint:@next no:priority
Select all relevant items
Set Priority = P2

Use bulk operations deliberately; a fast mistake is still a mistake.

28. INTERMEDIATE — Project Planning Patterns

This chapter combines the primitives into practical operating models.

28.1 Backlog Management

Recommended configuration:

Layout: Table
Filter: -status:Done no:sprint
Group by: Priority
Sort: Priority, then Target date
Fields: Type, Priority, Estimate, Team, Assignee

Backlog workflow:

flowchart LR
    A[Intake] --> B[Triage]
    B --> C[Prioritized Backlog]
    C --> D[Sprint / Release Commitment]
    D --> E[Execution]
    E --> F[Done]

28.2 Sprint Planning

Recommended configuration:

Sprint field: Iteration
Execution view: Board
Filter: sprint:@current
Columns: Status
Group by: Team
Field sum: Estimate

Planning steps:

Start from prioritized backlog.
Assign Sprint to candidate work.
Confirm estimates and owners.
Check field sums/capacity.
Resolve over-commitment.
Save the sprint view.

28.3 Kanban

Recommended configuration:

Layout: Board
Columns: Status
WIP limits: Selected active columns
No required iteration

Kanban is continuous flow. Avoid forcing sprint concepts into the model if the team does not use time boxes.

28.4 Roadmap

Recommended configuration:

Layout: Roadmap
Start: Start date
Target: Target date
Group by: Team or Workstream
Markers: Milestones
Zoom: Quarter

Roadmap items should represent decision-relevant work. A roadmap with hundreds of tiny tasks becomes a Gantt-shaped backlog rather than a strategy view.

28.5 Portfolio Tracking

A portfolio project can combine multiple repositories/teams with fields such as:

Strategic initiative
Team
Workstream
Priority
Target quarter
Health

Prefer a separate portfolio project only when portfolio metadata or access differs materially from team delivery projects. Do not duplicate all fields and manually synchronize them without a clear need.

Part V — ADVANCED AUTOMATION, APIs, SECURITY & GOVERNANCE

29. ADVANCED — GitHub Actions + Projects

GitHub Actions is useful when a project update must react to repository events or when the built-in project workflows are not expressive enough.

A good rule is:

Built-in workflow can do it?  -> Use the built-in workflow.
Repository event + custom rule? -> Consider GitHub Actions.
Cross-system/business logic?     -> Consider an App or external automation.

29.1 Projects Automation with Actions

Typical triggers include:

issues — issue opened, labeled, closed, reopened, assigned.
pull_request — PR opened, converted to ready-for-review, closed, merged.
workflow_dispatch — manual automation.
schedule — periodic cleanup or governance checks.
release/deployment events — update release-oriented metadata.

Automation Architecture

flowchart LR
    A[GitHub Event] --> B[GitHub Actions Workflow]
    B --> C{What is needed?}
    C -->|Add item| D[actions/add-to-project]
    C -->|Update fields| E[gh project or GraphQL API]
    C -->|Complex integration| F[GitHub App / External Service]
    D --> G[GitHub Project]
    E --> G
    F --> G

Example: Automatically Add Labeled Issues to a Project

Authentication matters. The repository-scoped GITHUB_TOKEN is not sufficient for accessing organization/user Projects. Use a token with appropriate Projects access, preferably a GitHub App installation token for organization automation or an appropriately scoped PAT where suitable.

name: Add roadmap issues to project

on:
  issues:
    types: [opened, labeled]

jobs:
  add-to-project:
    if: contains(github.event.issue.labels.*.name, 'roadmap')
    runs-on: ubuntu-latest

    steps:
      - name: Add issue to GitHub Project
        uses: actions/add-to-project@v2
        with:
          project-url: https://github.com/orgs/acme-corp/projects/7
          github-token: ${{ secrets.PROJECT_TOKEN }}

Use the built-in Auto-add to project workflow instead when a filter such as label:roadmap already expresses the requirement. The Action is more useful when additional repository logic is required.

29.2 Common Automation Patterns

Pattern	Example trigger	Action
Add project item	Issue gets `roadmap` label	Add issue to project
Set priority	Issue gets `severity:critical`	Set `Priority = P0`
Set Status	Deployment succeeds	Set `Status = Released`
Set date	Release created	Set target/release date
Assign iteration	Issue receives sprint label	Set Iteration field
Archive old work	Scheduled job	Archive matching completed items
Cross-repository intake	Events in many repositories	Add to shared organization project

Example: Event → Rule → Project Field

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub Issue
    participant GA as GitHub Actions
    participant API as Projects API
    participant P as Project

    Dev->>GH: Add severity:critical label
    GH->>GA: issues.labeled event
    GA->>API: Resolve project/item/field IDs
    GA->>API: Set Priority = P0
    API->>P: Persist field value

29.3 Authentication

The four terms below are easy to confuse:

Credential	Good fit	Important note
`GITHUB_TOKEN`	Repository-scoped Actions work	Do not assume it can access organization/user Projects
Classic PAT	Scripts/CLI where policy permits	GraphQL Projects commonly needs `read:project` for read and `project` for write
Fine-grained PAT	Endpoint-specific REST automation	Check the exact endpoint’s Projects permission requirements
GitHub App installation token	Organization-scale automation	Preferred for controlled, revocable, least-privilege integrations

Secure Token Pattern

Secret store
   |
   v
GitHub Actions secret / App token
   |
   v
Short-lived workflow execution
   |
   +--> Project API
   |
   +--> No token printed in logs

Do not:

hard-code PATs in workflow YAML;
echo access tokens;
give automation organization-wide permissions when one project is enough;
use a personal long-lived token for a business-critical integration without a lifecycle plan.

30. ADVANCED — GraphQL API for Projects

GitHub’s GraphQL API exposes the current Projects model as ProjectV2. GraphQL is still the most expressive API surface when you need rich discovery of Projects objects, node IDs, field configurations, and mutations.

30.1 `ProjectV2` API

The API frequently works with two identifiers:

Project number — the human-facing number in URLs, such as 7.
Node ID — the opaque GraphQL ID used by most mutations.

https://github.com/orgs/acme-corp/projects/7
                                      ^
                                project number

The normal automation flow is:

flowchart LR
    A[Know owner + project number] --> B[Query ProjectV2]
    B --> C[Get project node ID]
    C --> D[Query fields/items]
    D --> E[Get item/field/option IDs]
    E --> F[Run mutation]

30.2 Project Queries

Fetch an Organization Project and Its Fields

query($login: String!, $number: Int!) {
  organization(login: $login) {
    projectV2(number: $number) {
      id
      number
      title
      url
      fields(first: 50) {
        nodes {
          ... on ProjectV2Field {
            id
            name
            dataType
          }
          ... on ProjectV2SingleSelectField {
            id
            name
            options {
              id
              name
            }
          }
          ... on ProjectV2IterationField {
            id
            name
            configuration {
              iterations {
                id
                title
                startDate
                duration
              }
            }
          }
        }
      }
    }
  }
}

Run it with GitHub CLI:

gh api graphql \
  -f query='query($login:String!,$number:Int!){
    organization(login:$login){
      projectV2(number:$number){id number title url}
    }
  }' \
  -F login='acme-corp' \
  -F number=7

Read Project Items

query($login: String!, $number: Int!) {
  organization(login: $login) {
    projectV2(number: $number) {
      items(first: 100) {
        nodes {
          id
          type
          content {
            ... on Issue {
              number
              title
              url
            }
            ... on PullRequest {
              number
              title
              url
            }
            ... on DraftIssue {
              title
            }
          }
        }
      }
    }
  }
}

For larger projects, implement GraphQL pagination rather than assuming first: 100 is the whole project.

30.3 Project Mutations

Common current mutations include operations to:

create, update, close/reopen, and delete a project;
manage project collaborators;
add issues/PRs or draft issues;
update or clear item field values;
move/reorder, archive, or delete items;
create/update/delete fields;
create/update views;
link/unlink repositories and teams;
manage project templates and status updates.

Update Project Metadata

mutation {
  updateProjectV2(
    input: {
      projectId: "PROJECT_ID"
      title: "Acme Platform Delivery"
      public: false
      shortDescription: "Cross-repository platform delivery"
      readme: "# Delivery Project\n\nTeam operating guide."
    }
  ) {
    projectV2 {
      id
      title
      public
    }
  }
}

30.4 Project Item Mutations

Add an Existing Issue or PR

mutation {
  addProjectV2ItemById(
    input: {
      projectId: "PROJECT_ID"
      contentId: "ISSUE_OR_PR_NODE_ID"
    }
  ) {
    item {
      id
    }
  }
}

Important: adding an item and changing its project field value are separate operations. First add the item; then use the returned project-item ID in the update mutation.

Update a Text Field

mutation {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "PROJECT_ITEM_ID"
      fieldId: "FIELD_ID"
      value: { text: "Payments workstream" }
    }
  ) {
    projectV2Item {
      id
    }
  }
}

Update a Number Field

mutation {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "PROJECT_ITEM_ID"
      fieldId: "ESTIMATE_FIELD_ID"
      value: { number: 5 }
    }
  ) {
    projectV2Item { id }
  }
}

Update a Date Field

mutation {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "PROJECT_ITEM_ID"
      fieldId: "TARGET_DATE_FIELD_ID"
      value: { date: "2026-10-15" }
    }
  ) {
    projectV2Item { id }
  }
}

Update a Single-Select Field

Single-select fields use the option ID, not the display text.

mutation {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "PROJECT_ITEM_ID"
      fieldId: "PRIORITY_FIELD_ID"
      value: { singleSelectOptionId: "P0_OPTION_ID" }
    }
  ) {
    projectV2Item { id }
  }
}

Update an Iteration Field

mutation {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "PROJECT_ITEM_ID"
      fieldId: "ITERATION_FIELD_ID"
      value: { iterationId: "ITERATION_ID" }
    }
  ) {
    projectV2Item { id }
  }
}

Clear a Field Value

mutation {
  clearProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "PROJECT_ITEM_ID"
      fieldId: "FIELD_ID"
    }
  ) {
    projectV2Item { id }
  }
}

Project Field vs Issue/PR Metadata

updateProjectV2ItemFieldValue is for project-item fields. It does not replace issue/PR mutations for native metadata such as Assignees, Labels, Milestone, or Repository.

flowchart TD
    A[Need to change a value] --> B{Where does the value live?}
    B -->|Project field| C[updateProjectV2ItemFieldValue]
    B -->|Issue / PR property| D[Issue / PR GraphQL mutation]
    C --> E[Project item metadata]
    D --> F[Canonical Issue / PR metadata]

30.5 Project Field Mutations

A project automation may create or update custom fields, but treat schema changes like application schema changes: review them, name fields consistently, and avoid creating duplicates.

Typical field mutation lifecycle:

createProjectV2Field
       |
       v
updateProjectV2Field
       |
       v
deleteProjectV2Field

Before deleting a field, understand the reporting and automation impact because its values disappear with the field.

30.6 Linking APIs

Projects can be linked to repositories and teams for discoverability. API automation can manage these relationships for standardized project provisioning.

Example use case:

Create project template copy
        |
        +--> Link web repository
        +--> Link api repository
        +--> Link infra repository
        +--> Link platform team

30.7 Template APIs

At organization scale, template-related API operations are useful when you provision many consistent projects. Template governance should still happen at the organizational level; API automation should not become an excuse to create hundreds of nearly identical but unmanaged projects.

31. ADVANCED — REST API for Projects

Current GitHub REST documentation includes Projects endpoints for projects, items, draft items, fields, and views. This is important because older tutorials often state that current Projects are “GraphQL only.” That statement is no longer generally correct.

REST support is evolving. Verify the endpoint-specific token requirements, API version, and object support before standardizing production automation.

31.1 Project Endpoints

REST endpoints support operations around user and organization projects, including listing and retrieving projects.

A generic authenticated request pattern is:

curl --request GET \
  --url 'https://api.github.com/ORG_OR_USER_PROJECT_ENDPOINT' \
  --header 'Accept: application/vnd.github+json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-GitHub-Api-Version: 2026-03-10'

Do not copy an endpoint path from an old blog without checking the current REST documentation; Projects REST paths and supported operations have changed over time.

31.2 Item Endpoints

The REST Projects API includes operations for project items, such as listing, adding, retrieving, updating, deleting, and view-oriented item retrieval where supported.

REST item automation is useful when:

your integration is already REST-first;
the operation maps cleanly to a documented REST endpoint;
your security platform manages fine-grained REST permissions more easily.

GraphQL remains attractive when you need many connected Project objects in one response.

31.3 Draft Item Endpoints

Draft items can be created in current Projects through REST endpoints where documented for the relevant project owner type.

Drafts are useful for planning before deciding which repository should own the eventual issue.

flowchart LR
    A[Portfolio idea] --> B[Draft item]
    B --> C{Ready for engineering?}
    C -->|No| B
    C -->|Yes| D[Convert/create repository issue]

31.4 Field Endpoints

REST field endpoints can expose project field information and supported field-management operations. Be careful to distinguish:

project custom fields;
GitHub-provided Project fields;
issue fields owned by the organization;
native issue/PR metadata.

They can look similar in a table but have different ownership and mutation rules.

31.5 View Endpoints

Current REST documentation also includes Project view operations. Views are configuration, not copies of project data: an item belongs to the project and can appear in many views.

REST vs GraphQL Decision Table

Need	Prefer
Simple documented CRUD endpoint	REST
Rich nested Project object discovery	GraphQL
Existing REST enterprise integration	REST
Need exact ProjectV2 node IDs/field configuration in one query	GraphQL
Shell-first admin task	`gh project`
Event-driven repository automation	Actions + CLI/API

32. ADVANCED — GitHub CLI and Projects

GitHub CLI provides a dedicated gh project command family, making it the simplest automation layer for many administrator and developer workflows.

32.1 Authentication

Check your current authentication:

gh auth status

Add the minimum classic-token Projects scope used by gh project:

gh auth refresh -s project

For read-only API scripts, GitHub’s GraphQL Projects documentation also documents read:project; the gh project command family itself states project as its minimum required scope.

32.2 Discover Projects

# List organization projects
gh project list --owner acme-corp

# Include closed projects
gh project list --owner acme-corp --closed

# View project 7 in the browser
gh project view 7 --owner acme-corp --web

32.3 Create and Edit a Project

gh project create \
  --owner acme-corp \
  --title 'Acme Platform Delivery'

gh project edit 7 \
  --owner acme-corp \
  --description 'Cross-repository platform delivery' \
  --visibility PRIVATE

32.4 Fields

List fields:

gh project field-list 7 --owner acme-corp

Create a number field:

gh project field-create 7 \
  --owner acme-corp \
  --name 'Estimate' \
  --data-type NUMBER

Create a single-select field:

gh project field-create 7 \
  --owner acme-corp \
  --name 'Priority' \
  --data-type SINGLE_SELECT \
  --single-select-options 'P0,P1,P2,P3'

At the time of this guide, gh project field-create advertises TEXT, SINGLE_SELECT, DATE, and NUMBER. Do not assume every UI field type can be created with that CLI command.

32.5 Items

Add an issue:

gh project item-add 7 \
  --owner acme-corp \
  --url 'https://github.com/acme-corp/api/issues/42'

Create a draft item:

gh project item-create 7 \
  --owner acme-corp \
  --title 'Evaluate next authentication provider' \
  --body 'Discovery item for Q4 planning.'

List items using Project filter syntax:

gh project item-list 7 \
  --owner acme-corp \
  --query 'assignee:@me -status:Done'

Update a field by friendly names:

gh project item-edit 7 \
  --owner acme-corp \
  --url 'https://github.com/acme-corp/api/issues/42' \
  --field 'Status' \
  --value 'In Progress'

Update using machine-friendly IDs:

gh project item-edit \
  --id 'PROJECT_ITEM_ID' \
  --project-id 'PROJECT_ID' \
  --field-id 'ESTIMATE_FIELD_ID' \
  --number 5

Clear a field:

gh project item-edit \
  --id 'PROJECT_ITEM_ID' \
  --project-id 'PROJECT_ID' \
  --field-id 'FIELD_ID' \
  --clear

Archive an item:

gh project item-archive 7 \
  --owner acme-corp \
  --id 'PROJECT_ITEM_ID'

32.6 Repository and Team Linking

# Link to a repository
gh project link 7 \
  --owner acme-corp \
  --repo acme-corp/api

# Link to a team
gh project link 7 \
  --owner acme-corp \
  --team platform

32.7 Scripted Project Management

A common script discovers IDs once, then updates many items:

PROJECT_ID=$(gh project view 7 --owner acme-corp --format json --jq '.id')

STATUS_FIELD_ID=$(gh project field-list 7 \
  --owner acme-corp \
  --format json \
  --jq '.fields[] | select(.name == "Status") | .id')

printf 'Project: %s\nStatus field: %s\n' "$PROJECT_ID" "$STATUS_FIELD_ID"

For reliable production scripts:

use JSON output instead of parsing formatted tables;
fail when IDs are missing or duplicated;
quote shell variables;
make operations idempotent;
log identifiers, not credentials.

33. ADVANCED — GitHub Apps and Projects

A GitHub App is usually the strongest foundation for organization-owned automation because it separates the automation identity from an employee account and can use short-lived installation access tokens.

33.1 Authentication Model

sequenceDiagram
    participant S as Automation Service
    participant A as GitHub App
    participant G as GitHub
    participant P as Project API

    S->>A: Create signed app JWT
    A->>G: Request installation token
    G-->>A: Short-lived installation token
    A-->>S: Token
    S->>P: Call Projects API
    P-->>S: Result

33.2 Projects Permissions

When designing the App, grant only the Projects permissions and related repository/organization permissions required by the operation.

Examples:

Read dashboard integration
  -> Project read permission

Project field automation
  -> Project write permission

Automation also labels issues
  -> Add the corresponding Issues permission

Project access does not magically grant permission to all private repository contents referenced by project items. Permission design must consider both the project object and the underlying issue/PR repositories.

33.3 Installation Access Tokens

Benefits include:

short lifetime;
revocable App installation;
organization-controlled identity;
narrower permission model than a broad personal token;
clearer audit ownership.

33.4 Integration Pattern

flowchart TD
    A[Webhook / Schedule] --> B[GitHub App Service]
    B --> C[Validate Event]
    C --> D[Get Installation Token]
    D --> E[Query Project]
    E --> F[Apply Business Rule]
    F --> G[Mutation / REST Update]
    G --> H[Structured Audit Log]

Use a GitHub App when the automation is shared, business-critical, multi-repository, or expected to live longer than the individual who first built it.

34. ADVANCED — Project Security

Projects aggregate planning information from many repositories, so a project can expose organizational intent even when code remains protected.

34.1 Threat Model

Potentially sensitive project data includes:

unreleased product names;
vulnerability remediation plans;
incident follow-ups;
customer names;
acquisition/partnership work;
internal priorities and dates;
staffing/ownership metadata.

flowchart LR
    A[Public/Over-shared Project] --> B[Roadmap Exposure]
    A --> C[Priority Exposure]
    A --> D[Internal Naming Exposure]
    E[Over-privileged Token] --> F[Unauthorized Updates]
    G[Leaked Automation Secret] --> F

34.2 Least Privilege Checklist

Area	Secure default
Visibility	Private unless public planning is intentional
Human access	Read for observers; Write only for editors
Admin	Small owner/admin group
App/token	Minimum Projects + repo permissions
Secrets	Store in GitHub encrypted secrets or approved secret manager
Logs	Never print tokens; avoid unnecessary sensitive payloads
Outside collaborators	Explicit review
Templates	Do not embed real confidential draft items

34.3 Public Project Exposure

A public project can be viewable on the Internet, but a viewer still needs access to underlying private repository content to see those private items. Do not rely on that boundary as your only confidentiality control: project-level fields, draft issues, titles, documentation, or updates may themselves reveal sensitive planning data.

34.4 Automation Credential Security

Prefer this order for organization automation:

GitHub App installation token
        >
short-lived or narrowly scoped managed token
        >
long-lived personal credential

The final choice depends on the supported API and your organization’s authentication policy.

Secret Handling Example

permissions:
  contents: read

jobs:
  project-update:
    runs-on: ubuntu-latest
    steps:
      - name: Run project automation
        env:
          GH_TOKEN: ${{ secrets.PROJECT_TOKEN }}
        run: |
          gh project item-list 7 --owner acme-corp --format json >/tmp/items.json
          # Never: echo "$GH_TOKEN"

35. ADVANCED — Organization Governance

Organization governance answers a different question from project administration:

How do we make many projects understandable and safe across teams?

35.1 Governance Layers

flowchart TD
    A[Organization Policy] --> B[Templates]
    A --> C[Base Permissions]
    A --> D[Issue Field Taxonomy]
    A --> E[Visibility Rules]
    B --> F[Team Projects]
    C --> F
    D --> F
    E --> F
    F --> G[Purpose-Specific Views]
    F --> H[Automation]

35.2 Recommended Organization Standards

Governance area	Example standard
Status	Backlog, Ready, In Progress, In Review, Done
Priority	P0, P1, P2, P3
Estimate	Numeric field with documented scale
Iteration	One named Sprint field per delivery project
Visibility	Private by default
Template	Approved Engineering Delivery template
Ownership	At least two project admins
Archive	Auto-archive stale completed items
README	Required operating rules

35.3 Base Permissions

Set organization base project permission deliberately. Then layer explicit access through teams and named individuals.

A simple model:

Organization members: Read
Delivery team:         Write
Project maintainers:   Admin
Outside collaborators: No access unless explicitly required

The correct policy depends on how open internal planning is, but broad write/admin access should be intentional rather than accidental.

35.4 Project Creation and Templates

When many teams independently invent Status, Priority, and Sprint schemas, reporting becomes expensive. Organization templates should standardize the 80% common model while leaving room for team-specific views and a small number of local fields.

35.5 Team and Outside-Collaborator Access

Review these separately:

Can the person see the project?
Can the person edit project fields/views?
Can the person see the underlying private issue/PR?
Can the person administer the project?

Those are not the same capability.

36. ADVANCED — Enterprise Governance

Enterprise governance sits above organization-level conventions and focuses on policy consistency, security boundaries, supportability, and feature availability across organizations.

36.1 GitHub Enterprise Cloud vs GitHub Enterprise Server

Do not assume a GitHub.com tutorial maps one-for-one to every GitHub Enterprise Server (GHES) version.

Always verify:

whether the Projects feature exists in your GHES version;
the available API surface;
field/workflow/view support;
limits;
authentication behavior;
organization/enterprise policy controls.

flowchart TD
    A[Enterprise Standard] --> B[Organization A]
    A --> C[Organization B]
    A --> D[Organization C]
    B --> E[Team Projects]
    C --> F[Team Projects]
    D --> G[Team Projects]

36.2 Enterprise Governance Questions

Question	Why it matters
Who may create organization projects?	Prevent unmanaged sprawl
Which templates are approved?	Standardize planning models
What is the default visibility?	Protect roadmap metadata
Who can install automation Apps?	Control machine identities
Which token types are allowed?	Reduce credential risk
How long is completed project data retained?	Lifecycle/compliance
Which fields must be standardized?	Portfolio reporting
What works on the deployed GHES version?	Avoid unsupported design

36.3 Automation Policy

A mature enterprise separates automation into tiers:

Tier 1  Built-in Project workflows
Tier 2  Repository GitHub Actions
Tier 3  Shared GitHub App / platform automation
Tier 4  External portfolio/data platform integration

Use the lowest tier that meets the requirement. Every higher tier increases credential, maintenance, and observability responsibilities.

Part VI — ADVANCED PROJECT ARCHITECTURE & PLANNING

37. ADVANCED — Advanced Field Architecture

A field architecture is the vocabulary of your planning system. Good architecture lets people answer questions without creating a new field for every meeting.

37.1 Shared Metadata Strategy

Start with questions, not fields:

Question	Candidate field
What stage is this in?	Status
How important is it?	Priority
How large is it?	Estimate / Effort
Who owns the workstream?	Team
What business area is affected?	Product Area
When will we work on it?	Sprint / Iteration
When should it finish?	Target Date
Which release carries it?	Release

Recommended Core Model

Status       single-select / built-in Status
Priority     single-select or organization issue field
Estimate     number
Team         single-select or organization issue field
Workstream   single-select
Start Date   date
Target Date  date
Sprint       iteration
Release      single-select/text only if Milestone is not the right model

37.2 Status Taxonomy

Avoid statuses that encode multiple dimensions.

Good:

Backlog -> Ready -> In Progress -> In Review -> Done

Problematic:

Backend P1 In Progress
Frontend Blocked
Ready for Sprint 24

The problematic values mix team, priority, state, and iteration into one field.

flowchart LR
    A[Backlog] --> B[Ready]
    B --> C[In Progress]
    C --> D[In Review]
    D --> E[Done]
    C --> F[Blocked]
    F --> C

Blocked can be a Status when the team wants it to interrupt the flow, but for many organizations a separate blocker/dependency signal is cleaner because an item may be both “In Progress” and blocked.

37.3 Priority Taxonomy

A four-value scheme is usually enough:

Priority	Meaning
P0	Immediate/critical
P1	High
P2	Normal
P3	Low / opportunistic

Document whether P0 represents business priority, operational severity, or both. If incidents already have a Severity field, do not make Priority secretly duplicate Severity.

37.4 Effort Taxonomy

Two common models:

Model A: Number field -> 1, 2, 3, 5, 8, 13
Model B: Single-select -> XS, S, M, L, XL

Use number fields when you want sums/capacity analysis. Use categorical sizes when precision would be false confidence.

37.5 Team, Workstream and Product Area

These fields answer different questions:

Team         = who owns it?
Workstream   = which delivery stream does it belong to?
Product Area = what part of the product does it affect?

Example:

Item	Team	Workstream	Product Area
Add passkey login	Identity	Authentication Modernization	Account
Rotate DB credentials	Platform	Security Hardening	Infrastructure

37.6 Date Architecture

Use dates intentionally:

Start Date  = planned start of meaningful work
Target Date = planned completion / delivery target
Due Date    = only create separately if it means something materially different

Too many date fields create contradictory schedules.

37.7 Sprint, Quarter and Release

Prefer GitHub’s Iteration field for recurring sprints. A quarter can be represented by dates, a single-select field, or a higher-level planning model depending on reporting needs.

Do not use a single-select field named Sprint if the team actually needs iteration arithmetic such as @current, @next, and configured iteration breaks.

37.8 Organization Issue Fields vs Project Custom Fields

If a value should remain consistent wherever an issue appears in the organization, consider an organization-level issue field. If the value is specific to one project’s planning context, use a project field.

flowchart TD
    A[Need structured metadata] --> B{Should the value be canonical on the issue across projects?}
    B -->|Yes| C[Organization issue field]
    B -->|No| D[Project custom field]

A project can currently use up to 50 total fields, including system and issue fields, so field design is also a capacity decision.

37.9 Field Naming Conventions

Prefer names that survive team changes:

Priority          ✓
Target Date       ✓
Workstream        ✓
Platform Priority ✗ unless intentionally platform-specific
Rajesh Status     ✗ person-specific taxonomy
Q4 Sprint Name    ✗ date encoded into schema

38. ADVANCED — Work Breakdown and Hierarchy

GitHub Issues supports parent/sub-issue relationships, allowing multiple levels of hierarchy. Projects can surface parent relationships and sub-issue progress for planning.

38.1 Conceptual Hierarchy

Many teams use vocabulary like:

Initiative
  └── Epic
       └── Feature / Story
            └── Task / Bug

GitHub does not require you to use those exact product-management words. Model the hierarchy with Issues and issue types that match your organization.

flowchart TD
    A[Initiative: Modernize Authentication] --> B[Epic: Passkeys]
    A --> C[Epic: Session Security]
    B --> D[Feature: WebAuthn enrollment]
    B --> E[Feature: Recovery flow]
    D --> F[Task: API endpoint]
    D --> G[Task: UI enrollment]

38.2 Parent Issues and Sub-Issues

Use parent/sub-issue relationships when:

work has real decomposition;
progress at the parent matters;
child issues deserve separate ownership/discussion;
the hierarchy should remain visible outside one Project.

Do not create child issues merely to mimic checklist lines.

38.3 Sub-Issue Progress

Sub-issue progress gives a useful roll-up signal, but do not confuse item count with effort. Completing 8 tiny sub-issues out of 10 does not always mean the parent is 80% of the effort complete.

38.4 Issue Types

Default issue types include concepts such as Task, Bug, and Feature, and organizations can define custom issue types. Use types to describe what the issue is, not where it currently sits in the workflow.

Type:   Bug
Status: In Progress
Priority: P1

These dimensions should remain independent.

38.5 Dependencies

GitHub Issues also supports blocked by / blocking relationships.

Example:

flowchart LR
    A[Database schema change] -->|blocks| B[API migration]
    B -->|blocks| C[Frontend rollout]

Issue dependencies describe execution ordering; parent/sub-issues describe decomposition. They are not interchangeable.

38.6 Cross-Project Hierarchy

Because hierarchy lives on Issues, a parent and child can appear in different Projects. This is powerful for portfolio models, but establish clear ownership so two projects do not independently change the same canonical planning metadata.

39. ADVANCED — Capacity and Workload Planning

GitHub Projects gives you useful building blocks for capacity planning, but it is not a full workforce/resource-planning suite. Use estimates and field sums as decision support, not as mathematical certainty.

39.1 Basic Capacity Model

Sprint capacity = team's planned point/effort budget
Committed load  = sum(Estimate) for current iteration
Remaining room  = capacity - committed load

Example:

Team	Capacity	Current Sprint Estimate	Signal
Platform	34	31	Near capacity
API	40	46	Over plan
Web	32	25	Room remains

39.2 Project Setup

Fields:
  Iteration = Sprint
  Number    = Estimate
  Team      = owning team

View:
  Filter    = sprint:@current
  Group by  = Team
  Field sum = Estimate

flowchart LR
    A[Estimated Backlog] --> B[Assign Current Iteration]
    B --> C[Group by Team]
    C --> D[Sum Estimate]
    D --> E{Within Capacity?}
    E -->|Yes| F[Commit]
    E -->|No| G[De-scope / Rebalance]
    G --> B

39.3 Assignee Workload

A workload view can group by Assignee and sum Estimate. Use it to spot obvious overload, not to rank individual productivity.

Better question:

“Does one person own too much committed work?”

Poor question:

“Who produced the most story points?”

39.4 Iteration Workload

Roadmap and table views can help compare upcoming iterations. Be careful with carry-over work: if unfinished work moves sprint-to-sprint, your historical data may tell a different story than the current field value alone.

39.5 Capacity Anti-Patterns

Avoid:

treating story points as hours;
comparing teams with different estimation scales;
overfilling sprints because the arithmetic fits;
counting unestimated work as zero effort;
using assignee totals as performance scores.

40. ADVANCED — Portfolio and Program Management

An organization-level Project can act as a portfolio or program view across teams and repositories.

40.1 Portfolio Data Model

Recommended fields:

Strategic Initiative
Workstream
Owning Team
Priority
Health
Start Date
Target Date
Quarter
Release / Milestone

Use issue hierarchy to keep portfolio items at a useful level of abstraction.

flowchart TD
    A[Company Objective] --> B[Initiative: Identity Modernization]
    A --> C[Initiative: Cost Reduction]
    B --> D[Platform Epic]
    B --> E[Web Epic]
    B --> F[Mobile Epic]
    D --> G[Delivery Issues in Repo]
    E --> H[Delivery Issues in Repo]
    F --> I[Delivery Issues in Repo]

40.2 Multi-Team Project

A single organization Project can include items from many repositories and teams. Useful views include:

View	Layout	Filter / grouping
Executive roadmap	Roadmap	Group by Strategic Initiative
Team delivery	Board	Slice/Filter Team
Risks	Table	`priority:P0,P1 -status:Done` plus risk metadata
Quarter plan	Roadmap	Target dates within quarter
Current execution	Board	`sprint:@current`

40.3 Project Health

Portfolio-level health should be explicit through Project updates or a clearly governed health field on higher-level items.

Avoid inferring “green” simply because many issues are closed. A project can complete many low-risk tasks and still miss the critical path.

40.4 Cross-Project Coordination

Use separate team Projects when teams need distinct workflows/access, and a portfolio Project when leadership needs a shared strategic view. Do not duplicate every delivery issue into every portfolio project by default.

41. ADVANCED — Advanced Roadmap Planning

Roadmap views become useful when they communicate decisions, not when they reproduce every task on a timeline.

41.1 Long-Range Planning

A simple model:

Now      -> current committed work
Next     -> likely next work
Later    -> direction with lower certainty

For date-oriented roadmaps, configure Start Date and Target Date fields and use quarter/year zoom for higher-level planning.

41.2 Grouping Strategies

Choose one grouping that answers the audience’s question:

Group by Team       -> Who is delivering?
Group by Workstream -> What stream is progressing?
Group by Priority   -> What is strategically important?

41.3 Milestone and Iteration Markers

Markers add context to the timeline:

release milestones;
sprint boundaries;
important dates;
item-specific date markers.

They help readers compare planned work with external commitments.

41.4 Quarterly and Annual Planning

Example roadmap field set:

Field	Purpose
Start Date	Planned start
Target Date	Planned end
Team	Ownership
Priority	Strategic ordering
Milestone	Release marker
Workstream	Program grouping

41.5 Dependencies on a Roadmap

GitHub Issues can represent blocked by / blocking dependencies. Treat these as execution relationships. Do not assume the Project roadmap behaves like a full Gantt product with automatically scheduled dependency connector lines and critical-path calculations.

Use dependencies to answer:

What cannot start yet?
What work is holding another issue?
Which prerequisite must be watched?

42. ADVANCED — Advanced Kanban Design

A board should make flow problems obvious within seconds.

42.1 Workflow Columns

Example engineering flow:

Backlog | Ready | In Progress | In Review | Ready to Deploy | Done

Do not add a column for every tiny activity. More columns mean more transition overhead and less signal.

42.2 WIP Limits

A WIP limit communicates a desired maximum for a column. In Projects, treat the displayed limit as a planning signal, not a hard policy gate that prevents another card from entering the column.

Example:

In Progress: limit 6
In Review:   limit 4

If Review is constantly above its limit, the problem may be reviewer capacity rather than developer throughput.

42.3 Swimlane-Style Grouping

Use board grouping to create horizontal sections:

Columns: Status
Group:   Team

Conceptually:

             Ready | In Progress | Review | Done
Platform       3          2           1       8
API            4          3           2      11
Web            2          4           1       9

42.4 Purpose-Specific Boards

Board	Columns	Extra organization
Sprint board	Status	Filter `sprint:@current`
Priority board	Priority	Group by Team
Release board	Status	Filter milestone/release
Backlog board	Priority	Filter Status=Backlog/Ready
Team board	Status	Filter specific Team

42.5 Flow Optimization

Watch for:

cards aging in one status;
review queues growing;
too much simultaneous work;
many unowned cards;
large batches entering Done only at sprint end.

A board is valuable because it exposes system behavior, not because moving cards is visually satisfying.

43. ADVANCED — Advanced View Architecture

A mature Project has one data model and several purpose-specific views.

flowchart TD
    A[One Project Data Set] --> B[Executive Roadmap]
    A --> C[Engineering Sprint Board]
    A --> D[Product Backlog]
    A --> E[Team View]
    A --> F[Personal Work]
    A --> G[Risk View]
    A --> H[Done / Archive View]

43.1 Executive Views

Prefer:

higher-level items;
roadmap layout;
initiative/workstream grouping;
target dates and health;
minimal operational noise.

43.2 Engineering Views

Prefer:

current iteration;
status board;
assignee and estimate visible;
repository/team context;
PR/review state where useful.

43.3 Product Views

Prefer:

backlog and discovery items;
issue type;
priority;
product area/workstream;
target release/date.

43.4 Personal Workload View

Example filter:

assignee:@me -status:Done

Then group by Status or Iteration.

43.5 Risk View

Risk views should be rule-based where possible. Example concepts:

High priority + not Done
Past target date
Blocked work
Unassigned committed items
Items in current iteration without estimate

Some require metadata that Projects does not calculate automatically; create only the minimum fields/automation needed for meaningful risk detection.

43.6 Done/Archive Views

Completed work should remain discoverable without crowding delivery views. Use filters and auto-archive rather than deleting useful history.

44. ADVANCED — Reporting and Analytics Patterns

Project reporting should answer a decision question.

44.1 Reporting Matrix

Question	Useful view/chart
Where is work stuck?	Status distribution + board
Who/which team owns work?	Group by Team/Assignee
Are we overcommitted?	Iteration filtered field sums
What is high priority?	Priority distribution/table
Which repo carries load?	Group/chart by Repository
How much effort is planned?	Sum Estimate
What changed strategically?	Project update history

44.2 Progress Dashboard Pattern

flowchart LR
    A[Project Fields] --> B[Saved Views]
    A --> C[Insights Charts]
    A --> D[Project Updates]
    B --> E[Operational Decisions]
    C --> E
    D --> F[Stakeholder Communication]

44.3 Delivery Reporting

Avoid equating Done item count with delivered value. Complement status charts with:

target/milestone outcomes;
high-priority completion;
blocked work;
release/deployment facts;
qualitative Project updates.

44.4 Historical Analytics

Projects is primarily an operational planning tool. If you need long-term trend analysis, complex lead-time calculations, or enterprise BI, export/API-sync project data into an analytics system rather than overloading Project charts.

45. ADVANCED — Cross-Repository Project Design

One of current Projects’ strongest capabilities is planning across repositories.

45.1 Example Architecture

flowchart TD
    A[Organization Project: Acme Platform Delivery]
    B[web repo]
    C[api repo]
    D[infra repo]
    E[docs repo]

    B --> A
    C --> A
    D --> A
    E --> A

45.2 Repository Field

Use the built-in Repository metadata to:

filter one component;
group work by codebase;
compare workload distribution;
build repository-specific stakeholder views.

Example filters:

repo:acme-corp/web
repo:acme-corp/api status:"In Progress"

45.3 Auto-Add Across Repositories

Use multiple built-in auto-add workflows, subject to your plan’s workflow limits, when items should enter the project based on repository-specific filters.

Example:

web   -> label:platform
api   -> label:platform
infra -> label:platform

If logic becomes complex or spans many organizations/repositories, central App automation may be easier to govern than many duplicated Actions workflows.

45.4 Default Repository

Set a default repository when project-created issues should normally land in one repository. In a genuinely cross-repository program, teach users to verify the destination repository rather than blindly accepting the default.

45.5 Design Rule

Do not create one Project per repository merely because repositories are separate. Create Projects around planning boundaries: teams, programs, products, releases, or portfolios.

46. ADVANCED — Automation Architecture

Automation should reduce manual bookkeeping while preserving clear ownership and predictable behavior.

46.1 Automation Layers

flowchart TB
    A[Built-in Project Workflows]
    B[GitHub Actions]
    C[GitHub CLI Scripts]
    D[GraphQL / REST API]
    E[GitHub App]
    F[External Systems]

    A --> G[GitHub Project]
    B --> C
    B --> D
    C --> G
    D --> G
    E --> D
    F --> E

46.2 When to Use Which Layer

Requirement	Best starting point
Set Done when issue closes	Built-in workflow
Auto-add matching repo issues	Built-in auto-add
One-off admin script	`gh project`
Repository event + custom logic	GitHub Actions
Rich object discovery/update	GraphQL
Existing REST integration	REST API
Long-lived organization integration	GitHub App
BI/ITSM sync	App/external service

46.3 Event-Driven vs Scheduled

Event-driven:

Issue labeled -> update priority immediately
PR merged     -> update release status immediately

Scheduled:

Every day -> detect stale unowned work
Every week -> generate governance report

Prefer events when GitHub already emits the fact you need. Use schedules for reconciliation and conditions that require scanning state.

46.4 Idempotency

Every custom automation should be safe to run more than once.

Bad:

Every run creates another duplicate draft item.

Good:

Find existing item -> compare desired value -> update only if needed.

46.5 Observability

For business-critical automation, record:

event/request ID;
project/item IDs;
action attempted;
result;
non-secret error details;
retry outcome.

Do not make a planning system dependent on automation nobody can diagnose.

Part VII — ADVANCED INTEGRATIONS, ADMINISTRATION & REFERENCE

47. ADVANCED — Project Integration with GitHub Issues

Issues are the primary durable planning objects for most work tracked in Projects.

47.1 Issue Creation

You can create an issue from a Project or create it in a repository and add it to the Project.

CLI example:

gh issue create \
  --repo acme-corp/api \
  --title 'Add token rotation endpoint' \
  --body 'Implement the API required by the authentication rollout.' \
  --type Task \
  --project 'Acme Platform Delivery'

When creating from Projects, select the correct destination repository—especially in cross-repository projects.

47.2 Issue Metadata

Useful native issue metadata includes:

Assignees;
Labels;
Milestone;
Issue Type;
State / close reason;
Parent/sub-issue relationships;
dependencies;
organization issue fields where enabled.

These are canonical issue properties rather than ordinary project-scoped custom fields.

47.3 Issue Type

Use Issue Type to describe the nature of the work:

Bug
Feature
Task
Custom organization types

Do not duplicate this with a Project single-select field called Work Type unless the two truly mean different things.

47.4 Parent Issues and Sub-Issues

CLI examples:

# Create a child under parent issue 100
gh issue create \
  --repo acme-corp/api \
  --title 'Implement WebAuthn challenge endpoint' \
  --parent 100

# Add an existing issue as a sub-issue
gh issue edit 100 \
  --repo acme-corp/api \
  --add-sub-issue 123

Use the Project’s Parent issue and Sub-issue progress metadata to build hierarchy-oriented views.

47.5 Dependencies

CLI examples:

# Issue 140 is blocked by issue 123
gh issue edit 140 \
  --repo acme-corp/api \
  --add-blocked-by 123

Dependencies answer ordering/blocking questions; sub-issues answer decomposition questions.

47.6 Organization Issue Fields

Organization issue fields are designed for consistent metadata across an organization’s repositories and projects. Their values live on the issue and remain consistent across Projects.

Use them for organization-wide concepts such as:

Priority
Effort
Customer
Target date
Product area

Project custom fields remain appropriate for project-local concepts.

Synchronization Model

flowchart TD
    A[Issue] --> B[Organization Issue Field Value]
    B --> C[Project A]
    B --> D[Project B]
    A --> E[Project A Local Field]
    A --> F[Project B Local Field]

The organization field value is shared. Project-local values can differ by project.

48. ADVANCED — Project Integration with Pull Requests

Pull requests can be project items, and Projects can surface PR-specific metadata to connect planning with code review.

48.1 PRs as Project Items

A PR can be added directly:

gh project item-add 7 \
  --owner acme-corp \
  --url 'https://github.com/acme-corp/api/pull/88'

Direct PR tracking is useful for:

release readiness;
review queues;
migration programs;
dependency upgrades;
security remediation.

48.2 PR State and Review Metadata

Relevant metadata includes:

PR state: Open / Closed / Merged
Reviewers
Linked pull requests
Review status where exposed
Repository

Issue + PR Relationship

A useful model is:

flowchart LR
    A[Issue: User-visible requirement] --> B[Linked PR]
    B --> C[Review]
    C --> D[Merge]
    D --> E[Built-in workflow can mark project work Done]

Do not always add both an issue and its PR to the same delivery view. That can double-count work. Add PRs directly when the PR itself is the thing stakeholders need to track, or create a dedicated review/release view.

48.3 PR Automation

Typical rules:

PR opened             -> add to release project
PR ready for review   -> set Status = In Review
PR merged             -> built-in workflow sets Status = Done
PR closed unmerged    -> apply team-specific handling

Prefer built-in merge/close workflows where they meet the requirement.

48.4 Deployment and Release Tracking

Projects can coordinate implementation metadata, but deployment truth usually comes from Actions/deployment environments/release systems. If you copy deployment state into a Project field, automate it from the source of truth rather than relying on manual updates.

49. ADVANCED — Project Integration with Milestones

Milestones and Projects complement each other.

49.1 When Milestones Fit

Milestones work well for a repository-oriented target such as:

v3.2 release
Public Beta
Security Hardening Phase 1

Projects add richer planning around the work assigned to those milestones.

49.2 Useful Project Operations

You can:

show the Milestone field;
filter by milestone;
group items by milestone;
use milestone markers on roadmaps where supported;
create release-specific views.

Example conceptual filter:

milestone:"v3.2" -status:Done

49.3 Milestone vs Release Custom Field

Prefer the native Milestone when repository milestones are already your release source of truth. Create a custom Release field when you need organization-level semantics that a repository milestone cannot represent cleanly.

Avoid maintaining both manually with the same meaning.

50. ADVANCED — Project Integration with Teams

Teams provide a natural access and ownership boundary for organization Projects.

50.1 Team Linking

Linking a Project to a team improves discoverability and gives the team access according to GitHub’s team/project behavior.

CLI example:

gh project link 7 \
  --owner acme-corp \
  --team platform

50.2 Team Visibility vs Team Ownership Field

These are different:

Linked Team      = GitHub relationship/discoverability/access
Team field value = planning metadata on an item

A project may be linked to the Platform team while individual items have Team = Web, API, or Platform.

50.3 Team-Based Views

Examples:

View: Platform Delivery
Filter: team:Platform        # if Team is a filterable field with this value
Layout: Board
Columns: Status

For Project filter syntax, use the exact field name/value exposed in your project rather than assuming a built-in team: qualifier exists for your custom Team field.

50.4 Team Workload

Group by Team and sum Estimate to support sprint/program planning. Use capacity conversations to rebalance ownership, not to score teams.

51. ADVANCED — Project Integration with Repositories

Repositories remain the home of Issues and Pull Requests; Projects organize those objects across planning contexts.

51.1 Repository Linking

A linked Project can surface from a repository’s Projects area, improving discoverability.

gh project link 7 \
  --owner acme-corp \
  --repo acme-corp/api

51.2 Default Repository

A default repository streamlines creating issues from the Project. It is a convenience, not an ownership rule.

51.3 Importing and Adding Repository Items

Common approaches:

Repository import during project creation
Bulk add from repository
Search/add individual issues and PRs
Auto-add workflow
CLI/API automation

51.4 Repository Filters

Examples:

repo:acme-corp/api
repo:acme-corp/infra is:issue
repo:acme-corp/web -status:Done

51.5 Cross-Repository Project Rule

Repository boundaries should not force planning boundaries. A single product feature may require work in web, api, infra, and docs; one organization Project can show the complete delivery picture.

52. ADVANCED — Project Templates at Scale

Templates turn good project design into reusable organization infrastructure.

52.1 Template Portfolio

A mature organization may maintain a small curated set:

Template	Purpose
Engineering Delivery	Standard backlog + sprint execution
Product Roadmap	Strategic roadmap planning
Release	Release readiness across repos
Bug Management	Severity/priority triage
Platform Migration	Multi-repository migration
Program Portfolio	Initiative-level coordination

Avoid dozens of near-identical templates.

52.2 What to Standardize

A template should intentionally define:

fields and option taxonomies;
views;
configured built-in workflows that can be copied;
insights/charts;
README/instructions;
optional safe example draft items.

Remember that copied/template projects do not necessarily carry every relationship or all automation configuration. In particular, design post-creation steps for repository/team links, permissions, and auto-add workflows where needed.

52.3 Recommended Templates

Organizations can curate a limited set of recommended templates so users start from approved patterns rather than inventing a project model each time.

52.4 Template Versioning Strategy

GitHub project templates do not behave like a software package manager that automatically upgrades every project created from them.

Use a lightweight governance model:

Template README version: v3
Field standard: 2026-Q3
Owner: Platform PMO
Change log: link to governance repository

When the template changes, decide whether existing Projects should migrate. Do not assume they inherit changes automatically.

53. ADVANCED — Project Administration

Project administration is the operating discipline that keeps a Project trustworthy after its initial setup.

53.1 Administrative Areas

Area	Admin question
Settings	Is the title/description/README current?
Visibility	Is public/private still appropriate?
Access	Who has read/write/admin?
Fields	Are any duplicates or unused fields present?
Views	Are saved views purposeful and named?
Workflows	Are automations enabled and correct?
Insights	Do charts answer real questions?
Links	Are repositories/teams still relevant?
Updates	Is project health communicated?
Lifecycle	Should the project be closed or deleted?
Export	Is external reporting/recovery required?

53.2 Monthly Admin Review

[ ] Remove obsolete collaborators
[ ] Review public visibility
[ ] Check stale auto-add rules
[ ] Archive old completed items
[ ] Remove unused fields/views
[ ] Validate template/version conventions
[ ] Review Project README
[ ] Confirm at least two admins for important projects

53.3 Close vs Delete

Close a Project when the work is complete but history remains useful. Delete only when the Project itself should no longer exist and organizational policy allows it.

54. ADVANCED — Project Data Model

Understanding the data model prevents many API and reporting mistakes.

54.1 Conceptual Model

classDiagram
    class ProjectV2 {
      id
      number
      title
      public
      closed
    }
    class ProjectV2Item {
      id
      type
    }
    class Issue
    class PullRequest
    class DraftIssue
    class ProjectField
    class FieldValue
    class View
    class Workflow
    class Insight
    class StatusUpdate
    class RepositoryLink
    class TeamLink

    ProjectV2 "1" --> "many" ProjectV2Item
    ProjectV2Item --> Issue
    ProjectV2Item --> PullRequest
    ProjectV2Item --> DraftIssue
    ProjectV2 "1" --> "many" ProjectField
    ProjectV2Item "1" --> "many" FieldValue
    ProjectV2 "1" --> "many" View
    ProjectV2 "1" --> "many" Workflow
    ProjectV2 "1" --> "many" Insight
    ProjectV2 "1" --> "many" StatusUpdate
    ProjectV2 --> RepositoryLink
    ProjectV2 --> TeamLink

54.2 Critical Distinctions

Content ID vs Project Item ID

When you add Issue #42 to a Project:

Issue node ID          = identity of the issue
Project item ID        = identity of its membership in this Project

Field-value mutations target the project item ID, not simply the issue number.

Project Number vs Node ID

Project number = human-facing URL/reference
Project node ID = API identity used in GraphQL mutations

Field Configuration vs Field Value

Priority field          = schema/configuration
P1 option               = field option
Item's Priority = P1    = field value

Views Are Not Data Copies

A View contains presentation/query configuration. Items and field values belong to the Project data model and can appear in multiple views.

55. ADVANCED — Project API Authentication and Permissions

Authentication is part of the API design, not a final deployment detail.

55.1 Authentication Options

Method	Typical use
GitHub CLI login	Human/admin scripts
Classic PAT	GraphQL/CLI where policy permits
Fine-grained PAT	REST endpoints with explicit permission support
GitHub App installation token	Organization production automation
`GITHUB_TOKEN`	Repository Actions; do not assume Project access

55.2 GraphQL Projects Scopes

For classic PAT-based GraphQL Projects access, GitHub documents:

read:project -> query/read Projects
project      -> write/mutate Projects

The exact permissions for a GitHub App or fine-grained token should be selected from the current Projects permission model and the other resources your automation touches.

55.3 Permission Matrix Example

Automation action	Project access	Possible additional access
Read project items	Read	Underlying repo read if private content needed
Update custom field	Write	None beyond Project if no repo object modified
Add label to issue	Project + issue access as applicable	Issues write
Merge PR	Project access not enough	Pull requests/contents as required
Read private repo item details	Project visibility not enough	Repository permission

55.4 Least-Privilege Flow

flowchart TD
    A[Define operation] --> B[List Project permission needed]
    B --> C[List repository/org resource permissions needed]
    C --> D[Choose identity type]
    D --> E[Issue shortest/narrowest usable credential]
    E --> F[Test denied operations too]
    F --> G[Deploy and audit]

55.5 Authentication Failure Checklist

When an API call fails:

1. Is the token valid?
2. Does it include Projects read/write access?
3. Is SSO authorization required and satisfied?
4. Can the identity access the organization/project?
5. Can it access the underlying private repository item?
6. Is the API endpoint supported by this token type?
7. Is the API/version header current for the REST endpoint?

56. ADVANCED — Project Limits and Constraints

Limits change over time and can differ between GitHub.com plans and GitHub Enterprise Server versions. Treat this section as a design checkpoint and verify GitHub’s current documentation before building near a boundary.

56.1 High-Impact Current Limits

As verified for this guide:

Resource	Current documented limit / rule
Project items	Up to 50,000 items across active views and archive
Total fields in a Project	Up to 50, including issue fields and system fields
Organization issue fields	Up to 25 per organization
Single-select organization issue-field options	Up to 100
Recommended organization templates	Up to 6 recommended templates
Auto-add workflows — Free	1
Auto-add workflows — Pro	5
Auto-add workflows — Team	5
Auto-add workflows — Enterprise Cloud	20
Auto-add workflows — Enterprise Server	20 (verify your GHES version)

56.2 Functional Constraints to Remember

Auto-Add Filter Subset

Auto-add does not accept every Project filter qualifier. Current supported categories include a subset such as:

is:
label:
reason:
assignee:
no:

Design the rule in the UI and test it rather than assuming a complex saved-view filter can be pasted unchanged.

Auto-Add Is Not Historical Backfill

Enabling an auto-add workflow does not automatically import all existing matching items merely because they already satisfy the filter. The workflow acts when items are created or updated and match the rule. Backfill existing work separately when required.

Board WIP Limits Are Signals

Treat column limits as visible WIP guidance rather than enforcement that blocks card movement.

API Rate Limits

GraphQL and REST calls are subject to GitHub rate limiting. Bulk automation should paginate, cache stable IDs where appropriate, avoid unnecessary polling, and handle retry/rate-limit responses.

Layout/Field Restrictions

Not every field can drive every layout feature. Examples include:

Roadmap positioning requires date/iteration semantics.
Board columns are designed around suitable fields such as Status/single-select/iteration.
CLI field creation does not necessarily expose every field type available in the web UI/API.

56.3 Scale Strategy

Do not solve a 50,000-item boundary by deleting history randomly. Better strategies include:

Auto-archive completed work
Close completed projects
Split planning by real program/team boundary
Export/sync long-term analytics externally
Avoid adding irrelevant items in the first place

57. ADVANCED — Migration and Legacy Projects

Projects (classic) is historical. GitHub sunset Projects (classic), with removal announced for April 1, 2025 UTC. In 2026, new designs should target current GitHub Projects.

57.1 Concept Mapping

Projects (classic) concept	Current Projects concept
Board/card-centric project	Field-driven Project
Column	Often `Status` or another board column field
Note card	Draft issue
One board layout	Multiple saved Table/Board/Roadmap views
Card movement automation	Built-in workflows + field updates
Classic Project API types	`ProjectV2` / current REST Projects APIs

57.2 Why Migration Is Not Only Visual

Current Projects changes the planning model:

Classic: Card is primarily positioned in a board column.
Current: Item has structured fields; views render those fields differently.

A direct “copy columns exactly” migration can preserve old limitations instead of improving the planning model.

57.3 Migration Review Checklist

For legacy documentation/scripts/integrations, look for:

[ ] ProjectCard / ProjectColumn GraphQL types
[ ] addProjectCard / moveProjectCard mutations
[ ] Classic REST endpoints
[ ] Automation tied to board columns
[ ] Documentation saying Projects v2 is GraphQL-only
[ ] Old screenshots/UI instructions

Replace them with current Projects concepts and APIs.

57.4 Migration Design Steps

flowchart LR
    A[Inventory legacy model] --> B[Map columns to fields/status]
    B --> C[Define current views]
    C --> D[Rebuild automation]
    D --> E[Validate permissions]
    E --> F[Validate API/CLI scripts]
    F --> G[Document operating model]

58. ADVANCED — Project Best Practices

These practices keep a Project understandable months after launch.

58.1 Make the Project a Planning Source of Truth

Decide what the Project is authoritative for:

Sprint commitment?   Yes
Priority?            Yes, if governance says so
Issue description?   No — lives on the Issue
Code review state?   No — lives on the PR
Deployment truth?    Usually deployment system/Actions

58.2 Standardize Fields

Use a small, documented field set. Reuse organization issue fields when a value needs cross-project consistency.

58.3 Standardize Status

A shared Status vocabulary improves automation, reporting, and onboarding.

58.4 Use Purpose-Specific Views

One view should answer one audience question. Prefer 6 useful views over 25 nearly identical tabs.

58.5 Automate Mechanical State

Good automation candidates:

Auto-add matching work
Set initial Status
Set Done on close/merge
Archive stale completed work

Humans should spend time on prioritization and decisions, not clerical movement.

58.6 Manage Iterations Deliberately

Configure duration, cadence, names, and breaks. Use @current/@next filters so saved views advance with the calendar instead of needing weekly edits.

58.7 Publish Project Health

Use Project updates for stakeholder communication instead of forcing executives to infer health from card counts.

58.8 Control Access

Review public visibility, base permissions, team access, outside collaborators, and automation credentials.

58.9 Document the Operating Model

Every important Project should explain:

Purpose
Scope
Field meanings
Status definitions
View meanings
Automation rules
Ownership
Archive/lifecycle policy

58.10 Clean Up

Archive completed work, close obsolete Projects, delete unused fields/views, and retire stale automation.

59. ADVANCED — Common Project Anti-Patterns

Knowing what not to do prevents most long-term Project problems.

59.1 Too Many Custom Fields

Symptom: every stakeholder request creates another column.

Result: incomplete values, contradictory metadata, unusable tables.

Fix: require a decision question for every new field.

59.2 Duplicate Status Fields

Status
Engineering Status
Delivery Status
PM Status

Unless these represent genuinely different dimensions, they create ambiguity. Prefer one workflow Status and separate fields for distinct concepts.

59.3 Duplicate Projects

Two teams create separate Projects containing the same work because they need different views.

Fix: first ask whether one Project with two saved views solves the problem.

59.4 Excessive Manual Updates

If closing an issue requires someone to manually set Status = Done, enable the appropriate built-in workflow.

59.5 Unclear Ownership

Projects with no admin/maintainer become stale. Assign clear owners and at least one backup for business-critical planning.

59.6 Unsaved View Changes

A user carefully creates a filter/grouping but does not save the view. Others continue seeing the old configuration.

Fix: teach the visual “view modified” state and Save changes behavior.

59.7 Overly Complex Filtering

A filter nobody can explain is not a reliable process.

Break complex stakeholder needs into named views with clear purpose.

59.8 Poor Template Governance

Copying an old template forever multiplies bad fields and workflows. Assign owners and review template versions.

59.9 Missing Archive Strategy

A Project becomes slow to navigate conceptually because years of completed work remain mixed with active work.

Use filters plus auto-archive while retaining history.

59.10 Mixing Backlog and Completed Work

A default view with 5,000 Done items and 80 active items hides the work that matters.

59.11 Uncontrolled Public Visibility

Public roadmap metadata can reveal plans even when private repository issue bodies remain hidden.

59.12 Over-Broad Write Access

When everyone can restructure fields/views/workflows, nobody can rely on the model.

59.13 Inconsistent Iteration Usage

If half the team uses Sprint and half uses milestone labels, capacity and current-sprint views will be incomplete.

59.14 Manual Workflows Where Automation Fits

Automate deterministic state changes. Keep judgment-based decisions—priority, risk, scope—with people.

60. COMPLETE REFERENCE — GitHub Projects Feature Areas

Use this section as a revision checklist, implementation audit, or course syllabus map.

60.1 Feature Map

Area	What to know	Covered in
Learning about Projects	Purpose, concepts, ownership, discovery	1
Creating projects	Blank layouts, templates, repository import	2
Copying projects	Reusable configuration and copy caveats	2
Managing items	Issues, PRs, drafts, edit/archive/delete	3
Fields	Custom field types and lifecycle	4
GitHub metadata	Native issue/PR metadata	5
Views	Saved view architecture	6, 43
Table	Group/sort/filter/slice/sums	7
Board	Kanban, card movement, WIP guidance	8, 42
Roadmap	Timeline/date/iteration planning	9, 41
Filtering	Qualifiers, negation, relative dates/iterations	10
Sorting/Grouping/Slicing	Data organization	11
Iterations	Sprint configuration and capacity	12, 39
Status/state	Project Status vs issue/PR state	13
Built-in workflows	Status sync, close/reopen, add/archive	14-16
Insights	Charts and numeric aggregation	17, 44
Templates	Built-in/org/recommended/scale governance	18, 52
Project updates	Health and stakeholder updates	19
README/docs	Operating documentation	20
Visibility	Public/private behavior	21, 34
Access	Read/write/admin, teams/individuals	22
Linking	Repositories and teams	23, 50, 51
Lifecycle	Close/reopen/delete/cleanup	24, 53
Export	TSV/offline analysis	25
Command palette	Keyboard-driven commands	26
Productivity	Bulk editing and navigation	27
Planning patterns	Backlog, sprint, Kanban, roadmap, portfolio	28
GitHub Actions	Event-driven project automation	29
GraphQL	`ProjectV2` queries/mutations	30
REST API	Current Projects REST surface	31
GitHub CLI	`gh project` administration	32
GitHub Apps	Production machine identity	33
Security	Least privilege and exposure	34
Organization governance	Standards/templates/base access	35
Enterprise governance	Multi-org policy/version differences	36
Field architecture	Shared metadata taxonomy	37
Hierarchy	Parent/sub-issues, issue types, dependencies	38
Capacity	Estimate/iteration/team workload	39
Portfolio/program	Cross-team strategic planning	40
Cross-repository design	Shared organization planning	45
Automation architecture	Choosing built-in/Actions/API/App	46
Issues integration	Types, hierarchy, dependencies, issue fields	47
PR integration	Reviews, merge automation, releases	48
Milestones	Release/phase integration	49
Administration	Ongoing project operations	53
Data model	IDs, items, fields, views	54
API auth	Tokens, scopes, permissions	55
Limits	Item/field/workflow and functional constraints	56
Legacy migration	Projects (classic) transition concepts	57
Best practices	Sustainable operating model	58
Anti-patterns	Common design failures	59

60.2 Fast Decision Guide

flowchart TD
    A[What are you trying to do?]
    A --> B{Plan work visually?}
    B -->|Spreadsheet-like| C[Table]
    B -->|Flow/Kanban| D[Board]
    B -->|Timeline| E[Roadmap]
    A --> F{Automate?}
    F -->|Simple state/add/archive| G[Built-in Workflow]
    F -->|Repo event + logic| H[GitHub Actions]
    F -->|One-off/script| I[gh project]
    F -->|Rich API integration| J[GraphQL / REST]
    F -->|Long-lived org service| K[GitHub App]
    A --> L{Metadata scope?}
    L -->|Same across org issues| M[Organization Issue Field]
    L -->|Only this project| N[Project Custom Field]

60.3 Minimal Production-Ready Project

If you need a safe starting configuration, use:

Project: Organization-owned
Visibility: Private
Admins: 2+

Fields:
  Status
  Priority
  Sprint (Iteration)
  Estimate (Number)
  Team
  Start Date
  Target Date

Views:
  Backlog Table
  Current Sprint Board
  Roadmap
  My Work
  Risks

Workflows:
  Set initial Status
  Set Done on issue close / PR merge
  Reopen synchronization if required
  Auto-add where deterministic
  Auto-archive old completed items

Documentation:
  README with scope, field definitions, view meanings,
  automation rules, ownership, and lifecycle policy

End-to-End Hands-On Lab — Build `Acme Platform Delivery`

This lab connects the most important concepts into one practical exercise.

Lab Goal

Build an organization project that can manage backlog, sprint execution, roadmap planning, and basic automation across web, api, and infra repositories.

Step 1 — Create the Project

Create an organization-owned blank Table project named:

Acme Platform Delivery

Keep it private during setup.

Step 2 — Add Core Fields

Create/configure:

Status: Backlog, Ready, In Progress, In Review, Done
Priority: P0, P1, P2, P3
Sprint: Iteration, 2-week cadence
Estimate: Number
Team: Web, API, Platform
Start Date: Date
Target Date: Date

Step 3 — Add Sample Work

Create or add at least six issues across the three repositories:

web   #101 Add passkey enrollment screen
web   #102 Add recovery UX
api   #201 Add WebAuthn challenge endpoint
api   #202 Add recovery token endpoint
infra #301 Add authentication audit dashboard
infra #302 Rotate production signing keys

Step 4 — Build the Backlog View

Layout: Table
Group by: Priority
Sort: Priority, then Target Date
Show: Status, Priority, Team, Estimate, Sprint

Step 5 — Build the Sprint Board

Layout: Board
Columns: Status
Filter: sprint:@current
Group horizontally: Team
Show card fields: Priority, Estimate, Assignees
Field sum: Estimate

Step 6 — Build the Roadmap

Layout: Roadmap
Start: Start Date
Target: Target Date
Group by: Team
Zoom: Quarter

Step 7 — Create a Personal View

Filter: assignee:@me -status:Done
Layout: Table or Board

Step 8 — Enable Built-In Workflows

Configure appropriate rules to:

Set an initial Status when items enter the project
Set Status = Done when an issue closes / PR merges
Reopen/synchronize where your workflow requires it

Step 9 — Add Auto-Add

For each target repository, create an auto-add rule for a deliberate label such as:

label:platform

Remember: existing matching issues may need manual/bulk backfill.

Step 10 — Add an Insight

Create a chart showing item count by Status, optionally grouped by Team.

Step 11 — Write the README

Document:

Purpose
Repositories in scope
Status definitions
Priority definitions
Sprint cadence
View meanings
Automation behavior
Project owners

Step 12 — Test the Full Flow

flowchart LR
    A[Create Issue] --> B[Apply platform label]
    B --> C[Auto-add to Project]
    C --> D[Initial Status]
    D --> E[Assign Priority/Sprint/Estimate]
    E --> F[Move through Board]
    F --> G[Close Issue / Merge PR]
    G --> H[Status -> Done]
    H --> I[Auto-archive later]

Validation checklist:

[ ] Issue enters the correct Project
[ ] Status is initialized
[ ] Current sprint view includes it when assigned
[ ] Board movement changes the intended field
[ ] Roadmap uses the correct dates
[ ] Closing/merging updates Status as designed
[ ] Charts reflect the resulting data
[ ] Permissions prevent unintended editing

Operational Cheat Sheet

Everyday UI Tasks

Need	Fast path
Find my work	`assignee:@me -status:Done`
Current sprint	`sprint:@current`
Next sprint	`sprint:@next`
High priority unfinished	Priority P0/P1 + not Done
One repository	`repo:OWNER/REPO`
Open issues only	`is:issue is:open`
PRs only	`is:pr`
Missing assignee	`no:assignee` where supported by the relevant filter context
Items updated today	`updated:@today`

Everyday CLI Tasks

# Projects
gh project list --owner acme-corp

# Fields
gh project field-list 7 --owner acme-corp

# Items
gh project item-list 7 --owner acme-corp --limit 100

# Add issue/PR
gh project item-add 7 --owner acme-corp --url ISSUE_OR_PR_URL

# Create draft
gh project item-create 7 --owner acme-corp --title 'Draft idea'

# Update friendly field
gh project item-edit 7 --owner acme-corp --url ISSUE_URL --field Status --value 'In Progress'

# Link repository
gh project link 7 --owner acme-corp --repo acme-corp/api

Official References

GitHub Projects changes regularly. The following official references are the best places to verify behavior after this guide’s 2026-09-26 verification date.

GitHub Projects documentation
https://docs.github.com/en/issues/planning-and-tracking-with-projects
Quickstart for Projects
https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects
Adding items to Projects
https://docs.github.com/en/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project
Filtering Projects
https://docs.github.com/en/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects
Automating Projects
https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project
Using the GraphQL API to manage Projects
https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects
GraphQL Projects (ProjectV2) reference
https://docs.github.com/en/graphql/reference/projects
REST Projects API
https://docs.github.com/en/rest/projects
GitHub CLI gh project manual
https://cli.github.com/manual/gh_project
Official actions/add-to-project action
https://github.com/actions/add-to-project
GitHub Issues — sub-issues and dependencies
https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues
Organization issue fields
https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization

Final Takeaway

GitHub Projects becomes powerful when you stop thinking of it as “a board” and start treating it as a structured planning layer over GitHub Issues and Pull Requests.

The durable model is:

flowchart LR
    A[Issues / PRs / Drafts] --> B[Structured Fields]
    B --> C[Purpose-Specific Views]
    C --> D[Built-In Automation]
    D --> E[Insights + Project Updates]
    E --> F[CLI / APIs / Apps at Scale]
    F --> G[Governance + Security]

Keep the data model small, make views audience-specific, automate deterministic bookkeeping, preserve canonical issue/PR metadata, and use stronger API/App automation only when the built-in tools no longer express the requirement.

That combination gives you a Project that remains useful for developers, product teams, engineering managers, and organization administrators instead of becoming another board everyone stops updating.

rajeshkumar