Scope: Current GitHub Projects / Projects v2, not Projects (classic).
Audience: Developers, DevOps engineers, engineering managers, product managers, project administrators, and GitHub organization members.
Training duration: Approximately 2 hours, including guided practice.
Prerequisite: Basic familiarity with GitHub repositories, issues, and pull requests.
Learning style: Concept -> Why it matters -> See it -> Practice it -> Remember it.

1. What You Will Learn in 2 Hours

By the end of this tutorial, you should be able to:

• Explain what GitHub Projects is and how it differs from Issues, Pull Requests, and Milestones.
• Create an organization-level project.
• Add issues, pull requests, and draft issues.
• Create useful project fields such as Priority, Sprint, Estimate, Team, and dates.
• Build Table, Board, and Roadmap views.
• Filter, sort, group, and slice project data.
• Use iterations for sprint planning.
• Understand the difference between Project Status and Issue/PR state.
• Configure essential built-in workflows.
• Use auto-add and auto-archive safely.
• Apply basic access and visibility rules.
• Build a small but production-ready GitHub Project.

This guide intentionally leaves deep API, GraphQL, REST, GitHub App, enterprise governance, and portfolio architecture topics for the full reference guide.

2. Two-Hour Learning Plan

3. Running Example

Throughout the tutorial, imagine an organization named:

acme-corp

with three repositories:

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

We will create one organization project:

Acme Platform Delivery

and use it to manage work across all three repositories.

Recommended fields:

4. GitHub Projects Mental Model

GitHub Projects is a planning layer over GitHub work.

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]
    F --> H[Table]
    F --> I[Board]
    F --> J[Roadmap]
Code language: CSS (css)

The most important idea:

GitHub Projects does not replace Issues or Pull Requests. It organizes them for planning.

4.1 Projects vs Issues vs Pull Requests vs Milestones

Example:

Issue:
"Add passkey authentication"

Pull Request:
"Implement WebAuthn challenge endpoint"

Milestone:
"v3.2 Release"

Project:
"Acme Platform Delivery"
Code language: JavaScript (javascript)

4.2 One Project, Many Views

A Project stores items and metadata once.

Different views show the same data differently.

flowchart TD
    A[One Project Dataset] --> B[Backlog Table]
    A --> C[Current Sprint Board]
    A --> D[Product Roadmap]
    A --> E[My Work View]
Code language: CSS (css)

This is why you usually do not need separate Projects just because different people want different views.

5. Create Your First GitHub Project

For shared company work, prefer an organization-owned project.

5.1 UI Flow

flowchart LR
    A[Organization] --> B[Projects]
    B --> C[New Project]
    C --> D[Blank Project]
    D --> E[Table]
    E --> F[Name Project]
    F --> G[Configure Fields]
Code language: CSS (css)

5.2 Hands-On Steps

1. Open your GitHub organization.
2. Select Projects.
3. Select New project.
4. Start with a blank Table.
5. Name it:

Acme Platform Delivery

6. Keep it Private while configuring it.
7. Add a short description.

Example:

Cross-repository delivery planning for the Web, API, and Platform teams.

5.3 Why Start with Table?

The Table layout is the easiest place to:

• add fields;
• inspect metadata;
• bulk edit items;
• group work;
• clean up a backlog.

Board and Roadmap views can be added afterward.

6. Project Items

GitHub Projects supports three important item types.

6.1 Add an Existing Issue

From the project:

Add item -> Search repository -> Select issue

You can also paste an issue URL:

https://github.com/acme-corp/api/issues/201
Code language: JavaScript (javascript)

6.2 Add a Pull Request

A PR can also be a project item.

Example:

https://github.com/acme-corp/api/pull/88
Code language: JavaScript (javascript)

Track PRs directly when review or merge state is part of the project workflow.

6.3 Create a Draft Issue

Example:

Title: Add regional failover runbook

Body:
Document RTO, RPO, traffic cutover, database recovery, and rollback.
Code language: HTTP (http)

Draft issue lifecycle:

flowchart LR
    A[Idea] --> B[Draft Issue]
    B --> C[Refine]
    C --> D[Ready for Engineering]
    D --> E[Convert to Issue]
    E --> F[Choose Repository]
Code language: CSS (css)

6.4 Important Rule

Use:

Draft Issue -> when repository ownership is not decided
Issue       -> when work is real and should live in a repository
PR          -> when the code change itself is the tracking object

7. Project Fields

Fields turn a simple list of issues into a real planning system.

There are two categories.

7.1 GitHub Metadata

Examples:

Title
Assignees
Labels
Milestone
Repository
Issue Type
Issue State
PR State
Reviewers

These come from GitHub Issues and Pull Requests.

7.2 Project Custom Fields

Common field types:

Text
Number
Date
Single select
Iteration
Code language: JavaScript (javascript)

7.3 Field Selection Rule

Create a field only if you expect to:

Filter
Sort
Group
Slice
Aggregate
Automate
Report

Do not create a field just because someone mentioned a piece of information in a meeting.

8. Essential Fields to Create

For this tutorial, create the following fields.

8.1 Priority

Type:

Single select

Values:

Example:

Priority = P1

8.2 Team

Type:

Single select

Values:

Web
API
Platform

8.3 Estimate

Type:

Number
Code language: JavaScript (javascript)

Example scale:

1, 2, 3, 5, 8

Do not mix hours and story points in the same field.

8.4 Start Date and Target Date

Type:

Date
Code language: JavaScript (javascript)

Use these for Roadmap planning.

Example:

Start Date  = 2026-10-01
Target Date = 2026-10-15
Code language: JavaScript (javascript)

8.5 Sprint

Type:

Iteration

Example:

Sprint 24
Sprint 25
Sprint 26

An Iteration field is better than a text field named Sprint because GitHub understands concepts such as:

@previous
@current
@next
Code language: CSS (css)

8.6 Status

A useful simple workflow:

Backlog
Ready
In Progress
In Review
Done

flowchart LR
    A[Backlog] --> B[Ready]
    B --> C[In Progress]
    C --> D[In Review]
    D --> E[Done]
Code language: CSS (css)

Keep Status simple.

Too many statuses usually create confusion.

9. Practice: Add Sample Work

Add at least six issues or draft issues.

web   #101 Add passkey enrollment screen
web   #102 Add account 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
Code language: CSS (css)

Assign fields such as:

At this stage, you already have enough data to build useful views.

10. Project Views

A View is a saved way to look at the project.

A view can define its own:

Layout
Filter
Sort
Grouping
Slicing
Visible fields

We will create three essential views.

flowchart TD
    A[Acme Platform Delivery] --> B[Backlog - Table]
    A --> C[Current Sprint - Board]
    A --> D[Roadmap - Timeline]
Code language: CSS (css)

11. View 1 — Backlog Table

The Table layout is ideal for backlog management.

11.1 Configure the View

Name:

Backlog

Layout:

Table

Show fields:

Title
Status
Priority
Team
Sprint
Estimate
Assignees
Repository

Group by:

Priority

Sort:

Priority
Target Date
Code language: JavaScript (javascript)

11.2 Why This Works

The backlog answers:

What work exists?
What is most important?
Who owns it?
How large is it?
Has it been scheduled?

11.3 Dragging Between Groups

If your table is grouped by Priority:

P2 -> P1

Dragging an item between groups can update its Priority value.

The view becomes an editing interface, not just a report.

12. View 2 — Current Sprint Board

Boards are ideal for execution.

Create another view:

Current Sprint

Layout:

Board

Columns:

Status

Filter:

sprint:@current
Code language: CSS (css)

Optional horizontal grouping:

Team

Show card fields:

Priority
Estimate
Assignees

Conceptually:

             Ready | In Progress | In Review | Done
Web
API
Platform

12.1 Card Movement Updates Data

When Status drives the columns:

Ready -> In Progress

means:

Status = In Progress

The board is directly editing the Project field.

12.2 Work-in-Progress Limits

A board column can have an item limit.

Example:

In Progress limit = 5

Important:

A GitHub Projects WIP limit is a warning/signal, not a hard enforcement rule.

13. View 3 — Roadmap

Use Roadmap for timeline planning.

Create:

Roadmap

Layout:

Roadmap

Configure:

Start field: Start Date
Target field: Target Date
Group by: Team
Zoom: Quarter
Code language: JavaScript (javascript)

Example:

flowchart LR
    A[Web Work] --> B[October]
    C[API Work] --> B
    D[Platform Work] --> E[November]
Code language: CSS (css)

A real GitHub Roadmap renders these as timeline bars rather than flowchart nodes.

Use Roadmap for:

• quarterly planning;
• releases;
• multi-team coordination;
• major delivery windows.

Do not put every tiny engineering task on a long-term roadmap.

14. Filtering — The Most Important Daily Skill

A good saved view is mostly:

Useful data
+
Good filter
+
Right layout

14.1 Basic Filters

Status:

status:Done
Code language: CSS (css)

Not Done:

-status:Done
Code language: CSS (css)

Repository:

repo:acme-corp/api

My work:

assignee:@me
Code language: CSS (css)

Missing assignee:

no:assignee
Code language: CSS (css)

Missing priority:

no:priority
Code language: CSS (css)

14.2 Combine Filters

Current sprint bugs:

sprint:@current type:bug
Code language: CSS (css)

My unfinished work:

assignee:@me -status:Done
Code language: CSS (css)

High-priority incomplete work:

priority:P0,P1 -status:Done
Code language: CSS (css)

API work still open:

repo:acme-corp/api -status:Done

14.3 Date Filters

Today:

target-date:@today
Code language: CSS (css)

Next seven days:

target-date:@today..@today+7
Code language: CSS (css)

14.4 Iteration Filters

sprint:@previous
sprint:@current
sprint:@next
Code language: CSS (css)

This is one reason Iteration fields are so useful.

15. Sort vs Group vs Slice

These concepts are often confused.

Simple mental model:

Filter = What should I see?
Sort   = In what order?
Group  = In what sections?
Slice  = Which section/value do I want to focus on now?
Code language: JavaScript (javascript)

Example:

Filter: sprint:@current
Group: Team
Sort: Priority
Sum: Estimate
Code language: CSS (css)

This gives a very useful sprint planning table.

16. Sprint Planning with Iterations

A simple sprint setup needs only:

Sprint
Estimate
Status
Assignee or Team

16.1 Sprint Planning Flow

flowchart LR
    A[Prioritized Backlog] --> B[Choose Sprint]
    B --> C[Confirm Estimates]
    C --> D[Check Capacity]
    D --> E[Commit Work]
    E --> F[Execute on Board]
    F --> G[Review Result]
Code language: CSS (css)

16.2 Configure the Sprint

Example:

Duration: 2 weeks
Field: Sprint
Current: Sprint 24
Next: Sprint 25
Code language: HTTP (http)

Recommended saved views:

Current Sprint -> sprint:@current
Next Sprint    -> sprint:@next
Previous       -> sprint:@previous
Code language: CSS (css)

16.3 Capacity

Suppose:

API capacity      = 20 points
Committed Estimate = 22

Signal:

Potential overcommitment

Projects can sum Estimate values.

Your team still decides what the capacity number means.

Never use story-point totals to score individual engineers.

17. Project Status vs Issue State

This distinction matters.

Example:

Issue state     = Open
Project Status  = In Review

That is completely valid.

Why?

Because:

Issue state = GitHub object lifecycle
Status      = Planning workflow state

Another example:

PR state = Open
Project Status = In Review

When the PR merges:

PR state = Merged
Project Status = Done

can be automated.

18. Built-In Project Workflows

Before writing GitHub Actions or API scripts, check whether GitHub’s built-in workflows already solve the problem.

flowchart TD
    A[Need Automation] --> B{Built-In Workflow Enough}
    B -->|Yes| C[Use Built-In Workflow]
    B -->|No| D[Use Actions CLI or API]
Code language: PHP (php)

Built-in workflows are easier to maintain because they do not require custom code or credentials.

18.1 Set Initial Status

Example:

When item is added
Set Status = Backlog
Code language: JavaScript (javascript)

or:

Set Status = Todo
Code language: JavaScript (javascript)

depending on your workflow.

18.2 Set Done When an Issue Closes

Example:

Issue closed -> Status = Done

18.3 Set Done When a PR Merges

Example:

PR merged -> Status = Done

18.4 Reopened Work

Example:

Issue reopened -> Status = Ready

Use this only if that matches your team’s workflow semantics.

19. Auto-Add to Project

Auto-add lets GitHub add matching repository items to a Project.

Example requirement:

Add every open issue with label platform.
Code language: JavaScript (javascript)

Example filter:

is:issue is:open label:platform
Code language: CSS (css)

Workflow:

flowchart LR
    A[Issue Created or Updated] --> B{Matches Filter}
    B -->|Yes| C[Add to Project]
    B -->|No| D[Ignore]

19.1 Important Limitation

Auto-add is not the same as historical backfill.

If you enable a rule today, existing items that already matched earlier may still need to be bulk-added manually.

19.2 Good Uses

label:roadmap
label:platform
label:security
Code language: CSS (css)

Use clear labels or deterministic rules.

Avoid building dozens of fragile auto-add rules.

20. Auto-Archive

Completed work eventually clutters active views.

Auto-archive keeps the Project useful.

Typical lifecycle:

flowchart LR
    A[Active] --> B[Done]
    B --> C[Retention Period]
    C --> D[Archived]
Code language: CSS (css)

Example policy:

Completed work stays visible for 30 days.
Then it is archived.

Archive is usually better than delete because archived items can be restored and keep their Project context.

21. Insights — What Students Should Know

Insights create charts from Project data.

Useful examples:

Items by Status
Items by Priority
Estimate by Team
Work by Repository

Example:

Filter: sprint:@current
X-axis: Status
Group by: Team
Y-axis: Sum of Estimate
Code language: CSS (css)

Do not overbuild dashboards.

For a 2-hour course, remember:

Charts are only as good as the fields behind them.

If half the project has no Priority, a Priority chart is incomplete.

22. Permissions and Visibility — Essential Safety

Projects can be:

Private
Public
Code language: PHP (php)

For internal company work:

Private = safest default
Code language: PHP (php)

Typical access model:

Important:

Project permission does not automatically grant access to private repository content.

Also remember that a public Project can expose planning metadata even when linked repository content remains private.

Potentially sensitive information includes:

Roadmap dates
Internal priorities
Product codenames
Security remediation work
Customer names
Release plans

23. Minimal Production-Ready Project

A good starting configuration:

Project:
  Acme Platform Delivery

Owner:
  Organization

Visibility:
  Private

Admins:
  At least 2
Code language: PHP (php)

Fields:

Status
Priority
Sprint
Estimate
Team
Start Date
Target Date
Code language: JavaScript (javascript)

Views:

Backlog
Current Sprint
Roadmap
My Work
Risks

Workflows:

Set initial Status
Set Done when issue closes
Set Done when PR merges
Auto-add deterministic work
Auto-archive old completed work
Code language: JavaScript (javascript)

Documentation:

Purpose
Scope
Field definitions
Status definitions
View definitions
Automation rules
Ownership

24. Final 10-Minute Hands-On Lab

Build the complete flow.

Step 1 — Create Project

Acme Platform Delivery

Step 2 — Add Fields

Status
Priority
Sprint
Estimate
Team
Start Date
Target Date
Code language: JavaScript (javascript)

Step 3 — Add Six Items

Use the sample work from this guide.

Step 4 — Configure Backlog

Layout: Table
Group: Priority
Fields: Status, Priority, Team, Estimate, Sprint
Code language: HTTP (http)

Step 5 — Configure Sprint Board

Layout: Board
Columns: Status
Filter: sprint:@current
Group: Team
Code language: HTTP (http)

Step 6 — Configure Roadmap

Layout: Roadmap
Start: Start Date
Target: Target Date
Group: Team
Code language: HTTP (http)

Step 7 — Enable Workflows

Item added -> Initial Status
Issue closed -> Done
PR merged -> Done

Step 8 — Test the Complete Lifecycle

flowchart LR
    A[Create Issue] --> B[Add to Project]
    B --> C[Set Priority and Team]
    C --> D[Assign Sprint]
    D --> E[Move Through Board]
    E --> F[Close Issue or Merge PR]
    F --> G[Status Done]
    G --> H[Archive Later]
Code language: CSS (css)

Validation:

[ ] Item appears in the Project
[ ] Required fields are visible
[ ] Backlog grouping works
[ ] Sprint filter works
[ ] Board movement updates Status
[ ] Roadmap displays planning dates
[ ] Close or merge updates Status
[ ] Permissions are appropriate
Code language: CSS (css)

25. Essential Filter Cheat Sheet

26. Essential Design Rules

Remember these ten rules.

1. Use Issues for real repository work.
2. Use Draft Issues for ideas not ready for a repository.
3. Create one Project when multiple views can solve the audience problem.
4. Keep custom fields minimal.
5. Keep Status simple.
6. Use Iteration for sprints instead of free-text sprint names.
7. Use Table for planning and bulk editing.
8. Use Board for execution flow.
9. Use Roadmap for timeline communication.
10. Automate deterministic bookkeeping before building custom Actions or APIs.

27. Common Mistakes

Mistake 1 — Too Many Fields

Bad:

Priority
Business Priority
Engineering Priority
PM Priority
Customer Priority

Better:

One clearly defined Priority field

Mistake 2 — Too Many Statuses

Bad:

Todo
Ready
Ready for Dev
Development
Dev Complete
QA
QA Complete
Review
Ready for Release
Released
Closed

Use only the states that change a real operational decision.

Mistake 3 — Separate Project for Every Repository

Do not automatically create:

Web Project
API Project
Infra Project

when one shared delivery Project with repository filters would work better.

Mistake 4 — Manual Done Updates

If closing an issue always means the Project should show Done, automate it.

Mistake 5 — No Archive Policy

Years of completed work mixed with active work makes the Project harder to use.

Mistake 6 — Public by Accident

A public Project can reveal planning metadata.

Use Private unless public planning is intentional.

28. Optional 5-Minute Advanced Preview — CLI and Actions

This section is not required for the core 2-hour learning objective, but it helps students understand where Projects can go next.

28.1 GitHub CLI

List Projects:

gh project list --owner acme-corp
Code language: PHP (php)

List fields:

gh project field-list 7 --owner acme-corp
Code language: PHP (php)

List items:

gh project item-list 7 --owner acme-corp
Code language: PHP (php)

Add an issue:

gh project item-add 7 \
  --owner acme-corp \
  --url 'https://github.com/acme-corp/api/issues/201'
Code language: JavaScript (javascript)

28.2 GitHub Actions Example

If built-in auto-add cannot express your rule, GitHub Actions can add items.

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 project
        uses: actions/add-to-project@v2
        with:
          project-url: https://github.com/orgs/acme-corp/projects/7
          github-token: ${{ secrets.PROJECT_TOKEN }}
Code language: JavaScript (javascript)

Use custom automation only when built-in workflows are not enough.

29. What to Learn Next

After completing this 2-hour Essentials tutorial, continue with the full reference guide for:

GitHub Actions + Projects
gh project CLI
GraphQL ProjectV2
REST Projects API
GitHub Apps
Security architecture
Organization governance
Enterprise governance
Advanced field architecture
Parent and sub-issues
Dependencies
Capacity planning
Portfolio management
Advanced roadmaps
Advanced Kanban
Cross-repository architecture
Templates at scale
API authentication
Limits and constraints
Migration from Projects Classic
Code language: JavaScript (javascript)

30. Final Mental Model

If students remember only one diagram, make it this one:

flowchart LR
    A[Issues PRs Drafts] --> B[Project]
    B --> C[Fields]
    C --> D[Views]
    D --> E[Table Board Roadmap]
    B --> F[Workflows]
    F --> G[Less Manual Work]
Code language: CSS (css)

And one sentence:

GitHub Projects is a structured planning layer over GitHub Issues, Pull Requests, and Draft Issues, using fields, views, and automation to turn repository work into a manageable delivery system.

31. Student Revision Checklist

A student who can answer all of these is ready to use GitHub Projects effectively.

[ ] What is the difference between an Issue and a Project?
[ ] What are the three Project item types?
[ ] When should I use a Draft Issue?
[ ] What is a Project custom field?
[ ] Why use Iteration for Sprint?
[ ] What is the difference between Table, Board, and Roadmap?
[ ] What does filtering do?
[ ] What is the difference between filter, sort, group, and slice?
[ ] What does sprint:@current mean?
[ ] What is the difference between Project Status and Issue state?
[ ] What should happen when an issue closes?
[ ] What is Auto-add?
[ ] Why is Auto-archive useful?
[ ] What is the safest default Project visibility?
[ ] When should I prefer built-in workflows over GitHub Actions?
Code language: CSS (css)

32. Trainer Delivery Notes

For a live 2-hour class, do not spend equal time on every feature.

Recommended emphasis:

20% Concepts
50% UI demonstration and hands-on practice
20% Filters, sprint flow, and automation
10% Review and troubleshooting

The most valuable live demonstrations are:

1. Add an Issue to the Project.
2. Change fields inline.
3. Group a Table by Priority.
4. Drag a Board card from Ready to In Progress.
5. Filter using sprint:@current.
6. Create a Roadmap using Start Date and Target Date.
7. Close an Issue and show Status automation.
8. Explain why one Project can support many audiences through saved views.

Avoid spending core class time on GraphQL IDs, REST endpoints, or enterprise governance unless the audience specifically needs administration or automation engineering.

33. Official References

GitHub Projects changes regularly. Verify behavior using the current official documentation.

1. GitHub Projects documentation
   https://docs.github.com/en/issues/planning-and-tracking-with-projects
2. Quickstart for Projects
   https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects
3. 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
4. Filtering Projects
   https://docs.github.com/en/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects
5. Automating Projects
   https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project
6. GitHub CLI gh project
   https://cli.github.com/manual/gh_project
7. Official actions/add-to-project action
   https://github.com/actions/add-to-project

Final Takeaway

For an effective GitHub Projects implementation, start small:

Issues and PRs
      |
      v
Small Field Set
      |
      v
Backlog + Sprint + Roadmap Views
      |
      v
Built-In Automation
      |
      v
Simple Governance
Code language: JavaScript (javascript)

Do not begin with dozens of fields, complex APIs, or a portfolio hierarchy.

First make sure the team can answer:

What work exists?
What is important?
Who owns it?
What are we doing now?
What is next?
When is it expected?
What is done?

If GitHub Projects answers those questions clearly, the Project is already doing its most important job.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.