Skip to main content

Customizing the roadmap layout

You can use the roadmap layout to view your project's items on a timeline.

Note: Roadmaps for Projects are currently in public beta and subject to change.

About the roadmap layout

The roadmap layout provides a high-level visualization of your project across a configurable timespan, and allows you to drag items to affect their start and target dates. Roadmaps use your custom date fields to position your issues, pull requests, and draft issues on a timeline, allowing you to track work over time and watch progress.

For more information about changing a view to use the roadmap layout, see "Changing the project layout."

Setting the start and target date fields

You can set the date or iteration fields that your roadmap will use to position items. When you set a view to a roadmap layout, GitHub will attempt to use existing date and iteration fields you have already set up. If you choose an iteration field, you cannot add or edit iterations directly in the roadmap layout. For more information on creating new fields, see "About date fields" and "About iteration fields."

  1. In the top right of your roadmap, click Date fields.

    Screenshot showing the date field menu item

  2. Optionally, to create a new date or iteration field, click New field, type the name of your field, and click Save. You can then select the new field or create another.

    Screenshot showing the date field options

  3. Select a date or iteration field for "Start date" and "Target date."

    Screenshot showing the date field options

Setting the zoom level

You can choose the density of items on your roadmap. You can zoom in to show one month at a time or, for a greater overview, you can zoom out to show a quarter of a year or a full year.

  1. In the top right of your roadmap, click .

    Screenshot showing the zoom button

  2. Select either Month, Quarter, or Year.

    Screenshot showing the zoom level options

Showing and hiding fields

When you show and hide fields on the roadmap layout, you define which fields are shown when the side panel opens. This setting will not affect the information visible on the roadmap layout.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Under "Configuration", click and the list of currently shown fields. Screenshot showing show and hide fields menu option
  3. Select or deselect the fields you want to show or hide. Screenshot showing show and hide fields menu

Alternatively, open the project command palette by pressing Command+K (Mac) or Ctrl+K (Windows/Linux) and start typing "show", "hide", or the name of the field.

Grouping by field values

You can group items by a custom field value.

Note: You cannot group by title, labels, reviewers, or linked pull requests.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Click Group. Screenshot showing the group menu item
  3. Click the field you want to group by. Screenshot showing the group menu
  4. Optionally, to disable grouping, click No grouping at the bottom of the list. Screenshot showing "no grouping"

Alternatively, open the project command palette by pressing Command+K (Mac) or Ctrl+K (Windows/Linux) and start typing "Group by."

Showing the sum of a number field

You can configure a view to show the sum of one of more number fields, including a count of items in the group or column. For example, if you have a number field tracking the number of hours each item may take to complete, you can display of sum of those hours for each group or column.

In a board layout, field sums are displayed at the top of each column. In table and roadmap layouts, when you enable grouping by a field, field sums are included in each group's header.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon

  2. Click Field sum.

    Screenshot showing the field sum menu item

  3. Select the fields you want to include.

    Screenshot showing the field sum menu