GitHub Projects iterations: set up and run sprints

An iteration field is how GitHub Projects runs sprints. Each item gets one iteration, the iterations are dated blocks of time you define, and the project knows which one is running today. This guide sets one up, adds breaks, rolls unfinished work into the next sprint and filters by sprint, all in GitHub.

How do I create an iteration field?

Add it from a table view, the same way as any other custom field.

1. Open the project in a table view.
2. In the rightmost field header, click +.
3. Click New field and type the field's name, such as "Sprint".
4. Under "Field type", select Iteration.
5. If the first iteration should not start today, open the calendar next to "Starts on" and choose a date.
6. Set the duration: type a number and choose days or weeks.
7. Click Save.

GitHub creates three iterations straight away. The field counts toward the project's limit of 50 fields, built-in and custom together.

How do I add more iterations, change their length or add a break?

Everything after creation happens in the project settings.

1. Open the project and click the ⋯ menu in the top right.
2. Click Settings, then the name of the iteration field.
3. Click Add iteration to add one of the same length. To choose a different start date or length, click More options, set them, and click Add.
4. Click Save changes.

To edit one iteration, click its name to rename it, or click its dates to open the calendar, click the new start day and end day, and click Apply. The delete button on the right of each iteration removes it. You can also reach these settings from the table: click the field's header and choose Edit values.

Breaks cover holidays and planning weeks. In the same settings page, hover over the dividing line above an iteration and click Insert break. A new break takes the length of the most recently created iteration, and you can change its dates from the calendar before saving.

Iterations do not have to be equal. A two-week cadence with a one-week hardening sprint every quarter is a matter of editing that one iteration's dates.

Which iteration is the current one?

The current iteration is the one whose dates include today. GitHub works it out from the calendar, so there is nothing to start or close by hand. The filter keyword @current selects it, and @previous and @next select its neighbours:

• iteration:@current shows the sprint in progress.
• iteration:@next shows what is planned for the next sprint.
• iteration:@current..@current+3 shows this sprint and the three after it.
• iteration:<@current shows every earlier sprint.

Replace iteration with your field's name. The filter syntax guide lists the rest of the qualifiers you can combine with these, such as assignee:@me iteration:@current for your own sprint work.

How do I carry unfinished work into the next iteration?

Group by the iteration field and move the whole group.

1. Open a table view and group it by your iteration field (View → Group by).
2. Filter out finished work so only the unfinished items remain, for example -status:done.
3. Click the menu in the group header of the iteration you are closing.
4. Click Move items to… and choose the target iteration.
5. Confirm. Every item in that group now has the new iteration.

GitHub documents this bulk move for rolling work over, rescheduling and clearing a backlog iteration. It moves every item in the group, so step 2 decides what goes. Check the group's count before you confirm.

How do I plan and review sprints with views?

Three saved views cover most teams:

• This sprint: a board with iteration:@current, columns by Status. Standups happen here.
• Next sprint: a table with iteration:@next, grouped by assignee, with a field sum on your estimate field to check the load per person.
• Sprint planning: a board whose column field is the iteration field. GitHub lets any single-select or iteration field be the board's columns, and dragging a card to another column changes its iteration.

The roadmap layout can also place items by iteration. The roadmap view guide covers the date fields and markers it uses.

What can't GitHub iterations do?

The field stores which sprint an item belongs to. Nothing rolls unfinished work over on its own when a sprint ends: the Move items to… step above is manual, and someone has to remember to run it.

Linear is ahead here. Its cycles roll unfinished work into the next cycle automatically and track velocity, which is the workflow people coming from Linear expect on day one (checked 2026-08-22). If automatic rollover matters more to your team than keeping everything in GitHub, that is a fair reason to pick Linear.

How does Gitsu work with iterations?

Gitsu reads the iteration field and its calendar from GitHub and keeps writing back to it. The field itself stays a GitHub field.

What Gitsu does, per its code:

• Filters by sprint. @current, @previous and @next work in Gitsu's filter box. Gitsu reads the iteration calendar from GitHub and picks the iteration whose window contains today. If no iteration contains today, @current matches nothing rather than the whole board. Ranges over the keywords, such as @current..@current+3, are not supported yet.
• Sets an item's iteration. The iteration appears as a picker in an item's detail view, listing the iterations GitHub returned.
• Columns a board by iteration. Choose Columns and pick the iteration field. Lanes are ordered by start date, and dragging a card to another lane writes the new iteration to GitHub.
• Groups and sorts by iteration. A list grouped by the iteration field shows one group per sprint, and sorting by it orders items by the iteration's start date rather than its name.

What Gitsu does not do yet:

• Create or reshape the field. There is no screen to create an iteration field, add iterations or insert breaks. In the project settings drawer you can rename or delete a custom iteration field, and Open project settings on GitHub takes you to the page where the calendar lives.
• Show empty sprints on the board. An iteration board builds its lanes from the iterations its cards are in, so next sprint's lane appears only once one card is in it. Set the first card's iteration from its detail view, then drag the rest.
• Bulk-move a sprint. Gitsu's bulk bar edits Status, Priority, Assignee, Labels and Milestone, not the iteration. For a large rollover, use GitHub's Move items to….
• Automate cycles. Gitsu reads, filters and writes the iteration, and nothing runs when a sprint ends: no rollover and no velocity.

New to Gitsu? The getting-started guide connects your first project, and the desktop app runs the same views natively on macOS.