GitHub Projects
Learn how to organize and track your work using GitHub Projects, a flexible project management tool integrated with GitHub repositories.
GitHub Projects
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
The newer, more powerful implementation:
- Spreadsheet and board views
- Custom fields for detailed tracking
- More advanced filtering and sorting
- Powerful automations and workflows
- Enhanced integration with GitHub issues
- Saved views for different perspectives
Setting Up GitHub Projects
- Navigate to your profile, repository, or organization
- Go to the "Projects" tab
- Click "New project"
- Select a template or start from scratch
- Give your project a name and description
- Customize views, fields, and workflows
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
- Kanban-style workflow visualization
- Drag and drop card management
- Group by any field (status, assignee, etc.)
- Visual progress tracking
- Timeline visualization
- Date-based planning
- View work across time periods
- Identify dependencies and overlaps
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 }}
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
- Focus on board view with status columns
- Limit work in progress (WIP)
- Create automations for card movement
- Use labels for prioritization
- Add note items for process policies
- Group issues by feature or epic
- Use roadmap view to plan release timelines
- Create custom fields for feature status
- Track dependencies between features
- Link to design documents or specifications
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
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:
- Use the built-in charts for burndown analysis
- Create custom views for reporting
- Export project data for external reporting
- Track velocity with iteration fields
- Visualize work distribution across team members