How to link pull requests to project milestones in GitHub

Milestones are a project management feature that allows you to group issues and pull requests (PRs) around a specific goal or timeframe. Milestones are often used to track progress toward project deadlines, manage sprints, or align with release cycles.

By linking pull requests to milestones, you can make sure that development work aligns with broader project objectives, enabling better tracking of progress and resource allocation. In this guide, we’ll explore how to link pull requests to GitHub milestones and track them efficiently by incorporating tools like Graphite’s PR inbox for enhanced organization.

Steps to link pull requests to milestones in GitHub

1. Create or select a milestone

Before linking a pull request to a milestone, check that the milestone exists in your GitHub repository.

• Navigate to the Issues tab in your repository.
• Click on Milestones from the menu on the left.
• Select an existing milestone or create a new one by clicking New milestone.
• Set the title, due date, and description to define the milestone's scope.

2. Assign a milestone to a pull request

Once a milestone exists, you can assign it to a pull request directly.

1. Open the pull request you want to link.
2. In the right-hand sidebar under the Development section, click on Milestone.
3. Choose the relevant milestone from the dropdown list.

This links the pull request to the milestone, making it easier to track its contribution to the milestone's progress.

3. Use labels and custom filters for better tracking

To complement milestones, you can apply labels to pull requests to further categorize them by priority, type, or team responsibility. For example, use labels like frontend, backend, or high-priority to sort PRs linked to a milestone.

Enhancing workflow with the Graphite PR inbox

While GitHub provides native milestone tracking, tools like Graphite can further enhance your PR management strategies. Graphite’s PR inbox serves as an organizational hub for managing pull requests across multiple repositories, with customizable sections that streamline your view of PRs linked to milestones.

Setting up the Graphite PR inbox

1. Default repositories: Ensure your relevant repositories are added to Graphite’s PR inbox. On the free tier, you can select up to three default repositories, and up to 30 on Team or Enterprise tiers.
2. Create custom sections: Use the "Add new section" feature to filter PRs based on milestone association. For example, create a section showing all PRs linked to a specific milestone by configuring filters like milestone:<milestone-name>.
3. Rearrange sections for priority: Drag and drop sections in your inbox to keep milestone-related PRs easily accessible.

Benefits of using Graphite for PR management

• Centralized views: Group PRs by milestone across repositories, even if they aren’t in your default repository list.
• Search and filters: Use the Graphite search bar with milestone-related keywords to locate specific PRs quickly.
• Collaboration: Share section configurations with teammates to ensure consistent tracking of milestones.

Example workflow: Linking PRs to project milestones

Here’s a step-by-step example of linking pull requests to milestones and using Graphite for tracking:

1. Define a milestone: In GitHub, create a milestone called Feature-Launch. Assign a due date of December 15th.

2. Link PRs to the milestone: Assign all relevant pull requests to Feature-Launch using the milestone dropdown in GitHub.

3. Track in Graphite: Set up a custom section in Graphite’s PR inbox with the filter milestone:Feature-Launch. This will group all PRs associated with the milestone.

4. Collaborate efficiently: Share the custom section with teammates via Graphite to ensure everyone is aligned on milestone progress.

5. Monitor milestone completion: Use Graphite’s "Needs your review" section to prioritize milestone-related PRs requiring attention, ensuring the team meets the deadline.

Linking pull requests to milestones in GitHub encourages alignment between code contributions and project goals. By leveraging Graphite’s PR inbox, you can add even more organizational tools that simplify milestone tracking and collaboration.