Skip to main content

This version of GitHub Enterprise Server will be discontinued on 2024-03-07. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

About iteration fields

You can create iterations to plan upcoming work and group items.

You can create an iteration field to associate items with specific repeating blocks of time. Iterations can be set to any length of time, can include breaks, and can be individually edited to modify name and date range. With projects, you can group by iteration to visualize the balance of upcoming work, use filters to focus on a single iteration, and sort by iteration.

You can filter for iterations by specifying the iteration name or @current for the current iteration, @previous for the previous iteration, or @next for the next iteration. You can also use operators such as >, >=, <, <=, and ... For example, iteration:>"Iteration 4" and iteration:<@current. For more information, see "Filtering projects."

When you first create an iteration field, three iterations are automatically created. You can add additional iterations and make other changes on your project's settings page.

Adding an iteration field

  1. In table view, in the rightmost field header, click . Screenshot of a project. The "Add field" button is highlighted with an orange outline.
  2. Click New field.
  3. At the top of the dropdown, type the name of your new field.
  4. Under "Field type", select Iteration.
  5. Optionally, if you don't want the iteration to start today, select the calendar dropdown next to "Starts on" and choose a new start date.
  6. To change the duration of each iteration, type a new number, then select the dropdown and click either days or weeks.
  7. Click Save.

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

Adding new iterations

  1. Navigate to your project.

  2. In the top-right, click to open the menu.

    Screenshot showing a project's menu bar. The menu icon is highlighted with an orange outline.

  3. In the menu, click Settings to access the project settings.

  4. Click the name of the iteration field you want to adjust.

  5. To add a new iteration of the same duration, click Add iteration. Screenshot showing iteration settings. The "Add iteration" button is highlighted with an orange outline.

  6. Optionally, to customize the duration of the new iteration and when it will start, click More options, select a starting date and duration, and click Add. Screenshot showing iteration settings. The "More options" button is highlighted with an orange outline.

  7. Click Save changes.

Editing an iteration

You can edit iterations in your project settings. You can also access the settings for an iteration field by clicking in the table header for the field and clicking Edit values.

  1. Navigate to your project.

  2. In the top-right, click to open the menu.

    Screenshot showing a project's menu bar. The menu icon is highlighted with an orange outline.

  3. In the menu, click Settings to access the project settings.

  4. In the list on the left, click the name of the iteration field you want to adjust.

  5. To change the name of an iteration, click on the name and start typing. Screenshot of a single iteration's settings. The iteration name is highlighted with an orange outline.

  6. To change the date or duration of an iteration, click on the date to open the calendar. Click on the start day, then click the end day, and then click Apply. Screenshot of a single iteration's settings. The iteration date span is highlighted with an orange outline.

  7. Optionally, to delete an iteration, on the right of the iteration, click .

  8. Click Save changes.

Inserting a break

You can insert breaks into your iterations to communicate when you are taking time away from scheduled work. The duration of a new break defaults to the length of the most recently created iteration.

  1. Navigate to your project.

  2. In the top-right, click to open the menu.

    Screenshot showing a project's menu bar. The menu icon is highlighted with an orange outline.

  3. In the menu, click Settings to access the project settings.

  4. Click the name of the iteration field you want to adjust.

  5. Hover over the dividing line above an iteration, then click Insert break.

    Screenshot of the list of iterations for a project. On the dividing line between two iterations, a button, labeled "Insert break," is outlined in dark orange.

  6. Optionally, to change the duration of the break, click on the date to open the calendar. Click on the start day, then click the end day, and then click Apply.

  7. Click Save changes.