GitHub Projects

Learn how to organize and track your work using GitHub Projects, a flexible

GitHub Projects is a flexible project management tool that integrates directly with your GitHub issues and pull requests. It allows teams to plan, track, and manage their work efficiently while maintaining a close connection to their code repositories.

Understanding GitHub Projects

The original project board implementation:

  • Simple kanban-style boards
  • Basic automation for card movement
  • Limited customization options
  • Repository or organization level

Setting Up GitHub Projects

    1. Navigate to your profile, repository, or organization
    2. Go to the "Projects" tab
    3. Click "New project"
    4. Select a template or start from scratch
    5. Give your project a name and description
    6. Customize views, fields, and workflows
💡Tip

For team collaboration, organization-level projects are recommended as they can span multiple repositories and provide centralized tracking.

Key Features of GitHub Projects

Views

GitHub Projects offers multiple ways to visualize your work:

  • Spreadsheet-like interface
  • See all fields at once
  • Sort and group items
  • Perform bulk actions

Custom Fields

Enhance your tracking capabilities with custom fields:

  • Text fields: Add context and details
  • Number fields: Track metrics, story points, etc.
  • Date fields: Set deadlines and milestones
  • Single select fields: Create custom statuses or categories
  • Iteration fields: Group work into sprints
  • Labels: Categorize and tag items

Workflows and Automation

Streamline project management with automated workflows:

# Example workflow
name: Add issues to project

on:
  issues:
    types:
      - opened

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v0.4.0
        with:
          project-url: https://github.com/users/username/projects/1
          github-token: ${{ secrets.GITHUB_TOKEN }}
💡Note

Built-in workflow rules can automatically update fields, move items between statuses, or apply labels based on events without requiring GitHub Actions.

Project Management Best Practices

  • Use iteration fields for sprints
  • Set up statuses for "Backlog", "In Progress", "Review", and "Done"
  • Use number fields for story points
  • Create views filtered by current sprint
  • Group by assignee to see workload distribution

Integration with GitHub Issues and PRs

GitHub Projects provides seamless integration with issues and pull requests:

  • Issues and PRs can be added to projects directly
  • Status updates in projects can reflect in repositories
  • Converting project items to issues
  • Tracking PR status within project boards
  • Automatically closing items when PRs are merged
⚠️Caution

When deleting items from a project, the linked issues and PRs are not affected. However, deleting an issue or PR will remove it from all projects it's part of.

Project Insights and Reporting

Track progress and generate insights from your projects:

  1. Use the built-in charts for burndown analysis
  2. Create custom views for reporting
  3. Export project data for external reporting
  4. Track velocity with iteration fields
  5. Visualize work distribution across team members

Additional Resources

GitHub Projects Documentation

Official documentation for the new GitHub Projects

GitHub Project Templates

Learn about the available project templates