GitHub Projects

GitHub Projects provides Kanban-style project management directly in your repository. It helps teams plan, track, and manage work visually.

What is GitHub Projects?

Projects are flexible boards for organizing issues and pull requests:

┌─────────────┬─────────────┬─────────────┬─────────────┐
│   To Do     │ In Progress │  In Review  │    Done     │
├─────────────┼─────────────┼─────────────┼─────────────┤
│ Issue #1    │ Issue #3    │ PR #5       │ Issue #2    │
│ Issue #4    │ PR #6       │             │ PR #4       │
│ Issue #7    │             │             │             │
└─────────────┴─────────────┴─────────────┴─────────────┘

Creating a Project

Repository Project

1. Go to repository
2. Click "Projects" tab
3. Click "New project"
4. Choose a template or start blank
5. Name your project

Organization Project

1. Go to organization page
2. Click "Projects" tab
3. Create project spanning multiple repos

Project Templates

GitHub offers templates:

Template	Description
Board	Classic Kanban columns
Table	Spreadsheet-style view
Roadmap	Timeline view
Custom	Start from scratch

Board View

Classic Kanban with columns:

Default Columns

• Todo: Not started
• In Progress: Being worked on
• Done: Completed

Adding Custom Columns

Click "+ Add column":

• Backlog
• In Review
• Blocked
• QA Testing

Moving Items

Drag and drop between columns, or:

• Click item → Change status
• Automate with workflows

Table View

Spreadsheet-style for detailed tracking:

┌────────────┬────────┬──────────┬────────────┬─────────┐
│ Title      │ Status │ Assignee │ Priority   │ Due     │
├────────────┼────────┼──────────┼────────────┼─────────┤
│ Issue #1   │ Todo   │ @alice   │ High       │ Jan 15  │
│ Issue #2   │ Done   │ @bob     │ Medium     │ Jan 10  │
│ PR #3      │ Review │ @carol   │ High       │ Jan 12  │
└────────────┴────────┴──────────┴────────────┴─────────┘

Custom Fields

Add custom fields:

• Text: Notes, links
• Number: Story points, estimates
• Date: Due dates, sprints
• Single select: Priority, type
• Iteration: Sprint tracking

Roadmap View

Timeline for planning:

January                February               March
├────────────────────┼────────────────────┼────────────────────┤
│ ████████ Feature A │                    │                    │
│                    │ ████████████ Feature B                  │
│        ████ Bug Fix                     │                    │
│                    │              █████████████ Feature C    │

Use for:

• Release planning
• Sprint planning
• Milestone tracking

Adding Items

Add Existing Issues/PRs

1. Click "+ Add item"
2. Search for issue or PR
3. Select to add

Or drag from issue list.

Create Draft Items

Quick ideas before creating formal issues:

1. Click "+ Add item"
2. Type description
3. Add as draft

Convert to issue later:

• Click item → "Convert to issue"

Bulk Add

# Via CLI
gh project item-add 1 --owner org --url https://github.com/org/repo/issues/123

Automation

Built-in Workflows

Projects → Settings → Workflows:

Trigger	Action
Item added	Set status to "Todo"
Item reopened	Set status to "Todo"
Item closed	Set status to "Done"
PR merged	Set status to "Done"
Code review approved	Set status to "Review Complete"

Custom Automation

Use GitHub Actions:

# Auto-add new issues to project
name: Add to Project
on:
  issues:
    types: [opened]

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v0.5.0
        with:
          project-url: https://github.com/orgs/my-org/projects/1
          github-token: ${{ secrets.PROJECT_TOKEN }}

Filtering and Sorting

Filter Syntax

status:Todo
assignee:@me
label:bug
no:assignee
is:open
is:issue
is:pr
milestone:"v2.0"

Save Views

Create saved views for common filters:

1. Apply filters
2. Click "Save"
3. Name the view

Examples:

• "My Items": assignee:@me
• "High Priority": priority:High
• "Bugs Only": label:bug

Insights

Track project metrics:

• Items by status
• Items by assignee
• Burndown charts
• Velocity tracking

Access via "Insights" tab.

Best Practices

Keep It Updated

• Move items when status changes
• Don't let "In Progress" overflow
• Archive completed items

Use Consistent Fields

Define team conventions:

• What "In Progress" means
• When to move to "Review"
• Required fields

Limit WIP

Limit work in progress:

• Max 3-5 items per person
• Prevents overload
• Improves focus

Regular Grooming

• Weekly review of backlog
• Archive stale items
• Update priorities

CLI Commands

# List projects
gh project list

# View project
gh project view 1

# Add item
gh project item-add 1 --owner org --url issue-url

# Update item
gh project item-edit --id ITEM_ID --field-id FIELD_ID --value "Done"

Integration with Other Tools

GitHub CLI

Full project management from command line.

API

GraphQL API for custom integrations:

query {
  organization(login: "my-org") {
    projectV2(number: 1) {
      items(first: 10) {
        nodes {
          content {
            ... on Issue {
              title
            }
          }
        }
      }
    }
  }
}

Third-Party Tools

• Jira sync
• Slack integration
• Zapier automation

Summary

• Projects provide Kanban-style management
• Board, Table, and Roadmap views available
• Add custom fields for your workflow
• Use automation for status updates
• Filter and save views
• Track progress with insights
• Keep boards updated and groomed

In the next lesson, we'll learn about GitHub Actions.