p2 GitHub Project Scheduler

p2 is a statistical scheduling engine that turns prioritized, estimated tasks into realistic completion date ranges. The p2-github-scheduler GitHub Action applies p2 to GitHub Projects by reading issue estimates and dependencies, then automatically calculating and updating completion dates.

Key Features

• Automatic Scheduling - Runs whenever issues are updated and daily
• Statistical Analysis - Calculates realistic date ranges from estimate uncertainty
• Task Dependencies - Respects GitHub’s issue blocking relationships
• Estimate Ranges - Low and high estimates for confidence intervals
• Scheduling Warnings - Automatic comments explain why issues can’t be scheduled
• Zero Configuration - Auto-detects projects from issues

Quick Start

1. Install the p2 GitHub App on your repositories
2. A pull request will automatically be created to add the workflow file
3. Merge the PR to enable automatic scheduling

That’s it! Issues will be automatically rescheduled whenever they are updated and daily at 6am UTC.

Using p2

Set estimates on your issues:

• Low Estimate - Optimistic estimate in hours
• High Estimate - Pessimistic estimate in hours

Prioritize your work:

• Use a list view in your GitHub Project to order issues by priority
• Higher priority issues (earlier in the list) are scheduled first

Optional settings:

• Due Date - Set a deadline for an issue
• Scheduling Status - Set to “On Hold” to exclude an issue from scheduling

Learn more:

• How to Estimate →

GitHub Project Fields

p2 uses the following custom fields, which are automatically created if they don’t exist:

Field Name	Type	Description
Low Estimate	Number	Optimistic estimate in hours
High Estimate	Number	Pessimistic estimate in hours
Due Date	Date	Optional deadline for the task
Scheduling Status	Single select	Set to “On Hold” to exclude from scheduling
Expected Start	Date	Calculated start date
Expected Completion	Date	Mean completion date
98% Completion	Date	98th percentile completion date

How It Works

1. When an issue is updated, the GitHub Action runs
2. All issues in the project are fetched with their estimates and dependencies
3. p2’s scheduler runs statistical analysis to calculate completion date ranges
4. The calculated date fields are updated in GitHub Projects

The scheduler also runs on a daily schedule (6am UTC by default) to keep dates current as time passes. The schedule can be customized by editing the cron expression in the workflow file.

The scheduler considers:

• Task dependencies via GitHub’s blocking relationships
• Estimate uncertainty using low/high ranges
• Assignee workload for parallel task scheduling
• Milestones as task groupings

Scheduling Warnings

When an issue cannot be scheduled, a comment is automatically posted explaining the problem. Comments are automatically removed when the issue becomes schedulable.

Issues cannot be scheduled when:

• Dependency cycle - The issue is part of a circular dependency chain
• Missing dependency - The issue depends on another issue not in the project
• On-hold dependency - The issue depends on an issue with Scheduling Status “On Hold”
• Missing estimate - Only one of Low Estimate or High Estimate is set
• Invalid estimate - High Estimate is less than Low Estimate

Additionally, a warning is posted when:

• At risk - The Expected Completion date is after the Due Date

At-risk warnings do not prevent scheduling - they only warn that the deadline may be missed.

Statistical Scheduling

p2 uses statistical scheduling to calculate realistic completion dates:

1. Each task’s duration is computed from low/high estimates
2. Dependencies are respected when scheduling tasks
3. The scheduler reports the mean (Expected Completion) and 98th percentile dates

This approach captures the uncertainty inherent in estimates, and provides meaningful confidence intervals rather than single-point predictions.