What this article covers:
- The benefits of using milestones in project planning
- How to sync GitHub milestones to Asana
- Tips and limitations of this sync
The benefits of using milestones in project planning
Milestones are a great way to group issues into projects, features or even time periods in GitHub. It helps teams find their way in the ever growing list of issues and focus on what needs to be done.
This information is essential when you are planning work with your team so it was a priority to let you sync your GitHub Milestones with your favorite project management tool.
We take advantage of Asana's custom fields feature to sync your GitHub milestones. If you don't have access to this feature (only for Asana Premium users) you can still sync GitHub milestones in Asana's task description footer. You should also map GitHub milestone due date with Asana task due date.
You can find this field mapping under the "Fields" tab of your Unito sync settings.
How to sync GitHub milestones to Asana
Create your custom field
Before you can sync the GitHub milestone to a custom field, you need to create that field in the destination app. This is supported in Asana, Wrike and Jira. Here's how to do it in Asana:
Create a “Milestone” custom fields in Asana (type: Text). It has to be created in the same workspace where the synced project will live. That’s it for Asana. You don’t need to activate it in your projects in Asana, this will be done automatically when you will map it in Unito.
Map the fields in Unito
Go to your sync settings in Unito and click on the “Fields” tab. You will see a bunch of fields from Asana and GitHub that are already mapped together.
Click on “Create New” and choose “Milestones” in the GitHub drop-down menu and “Milestone” (or whatever you called your custom field) in the Asana drop-down menu. Click “Add”.
Note that this will instruct Unito to populate the custom field with the name of the GitHub Milestone.
The good news is that you can also map the Milestone due date from GitHub to the task due date in Asana, just map the according fields.
For that, click on "Create New", and choose "Milestone Due Date" on the GitHub side, "Due Date" from the Asana drop-down menu, and click "Add".
Save your settings and that’s it! Your project(s) will start populating with GitHub Milestone information!
Tips and limitations
- You can do an advanced search in Asana to easily find all the tasks from a specific Milestone
- Click on ‘Search’ > ‘Advanced Search’ in Asana
- There click on ‘Add Filter’
- You can choose a Custom Field with a specific name
- You can save, favorite, and even rename the search
- When you change the task due date on Asana it will not change the Milestone due date in GitHub (to make sure you don’t accidentally change every other issue due date)
- You can change the Milestone or fill one directly in Asana. Unito will look for for the closest matching Milestone in GitHub and add it to the issue (for example ‘Sprint 5’, ‘Sprint5’, ‘Sprint-5’ will match to the same Milestone for Unito, but ‘Sprint 4’ and ‘Sprint 55’ won’t. Neither will ‘Sprint 2.1.0’ and ‘Sprint 2.10’ match.)
- If you set the custom field to a value that doesn't match any existing GitHub Milestone, it won't modify the corresponding issue in GitHub.
- A Milestone cannot be created via Asana, Unito will always look for an existing one. We recommend you create the Milestone directly in GitHub.