doc/user/group/iterations/_index.md
{{< details >}}
{{< /details >}}
An iteration in GitLab refers to a time-boxed workflow that groups issues to be worked on during a specific period of time, usually lasting 1-3 weeks.
Teams can use iterations to track velocity and volatility metrics. For tracking the same item over multiple concurrent periods, you can use iterations with milestones. Create and manage various iteration cadences in a group.
For example, you can use:
In GitLab, iterations are similar to milestones, with a few differences:
You can use iterations to organize and track work in fixed time periods. The following examples show how iterations help teams maintain consistent delivery cycles.
Use iterations to plan and execute work in fixed time periods, and help teams maintain a predictable delivery cadence. When teams work in sprints, each iteration provides a clear timebox for planning, execution, and delivery of work items. For more information, see the use GitLab to facilitate Scrum tutorial.
For example, when running two-week sprints, teams often need to coordinate multiple workstreams. The development team tracks implementation in the current sprint, while product managers prepare backlog items for upcoming sprints.
By using iterations:
This structure helps teams complete work consistently while maintaining visibility into progress.
When you set up iterations for sprints:
Use iterations to support shorter development cycles when your team needs frequent releases. When practicing methodologies like Extreme Programming (XP), teams can use one-week iterations to maintain fast feedback loops.
For example, when implementing rapid changes, teams might deploy to production multiple times per iteration. The team tracks their work in weekly iterations while maintaining the flexibility to release whenever code is ready.
By using iterations:
This approach helps teams balance agile practices with organized planning.
When you use iterations for rapid cycles:
{{< history >}}
iteration_cadences. Disabled by default.iteration_cadences removed.{{< /history >}}
Iteration cadences are containers for iterations and can be used to automate iteration scheduling. You can use them to automate creating iterations every 1, 2, 3, or 4 weeks. You can also configure iteration cadences to automatically roll over incomplete issues to the next iteration.
{{< history >}}
{{< /history >}}
Prerequisites:
To create an iteration cadence:
In the top bar, select Search or go to and find your group.
Select Plan > Iterations.
Select New iteration cadence.
Enter the title and description of the iteration cadence.
To manually manage the iteration cadence, clear the Enable automatic scheduling checkbox and skip the next step.
Complete the required fields to use automatic scheduling.
Select Create cadence. The cadence list page opens.
To manually manage the created cadence, see create an iteration manually.
To view all the iterations in a cadence, ordered by descending date, select that iteration cadence. From there you can create a new iteration or select an iteration to get a more detailed view.
[!note] If a project has issue tracking turned off, to view the iterations list, enter its URL. To do so, add:
/-/cadencesto your project or group URL. For examplehttps://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences. Issue 339009 tracks improving this.
Prerequisites:
To edit an iteration cadence:
2
doesn't delete the eight existing upcoming iterations.Suppose it's Friday, April 15, and you have three iterations in a manual iteration cadence:
The earliest possible Automation start date you can choose in this scenario is Saturday, April 16, because April 15 overlaps with the ongoing iteration.
If you select Monday, April 18 as the automation start date to automate scheduling iterations every week up to two upcoming iterations, after the conversion you have the following iterations:
Your existing upcoming iteration "Tuesday, April 12 - Friday, April 15" is changed to "April 18 - Sunday, April 24".
An additional upcoming iteration "April 25 - Sunday, May 1" is scheduled to satisfy the requirement that there are at least two upcoming iterations scheduled.
{{< history >}}
{{< /history >}}
Prerequisites:
Deleting an iteration cadence also deletes all iterations in that cadence.
To delete an iteration cadence:
When iteration roll-over is enabled, at the end of the current iteration, all open issues are moved to the next iteration.
Iterations are changed by the special GitLab Automation Bot user, which you can see in the issue system notes. This user isn't a billable user, so it does not count toward the license limit count.
On GitLab.com, this is the automation-bot1 user.
{{< history >}}
{{< /history >}}
When an iteration cadence has automatic scheduling enabled, iterations are created on schedule. If you disable that option, you can create iterations manually.
Prerequisites:
To create an iteration:
{{< history >}}
{{< /history >}}
Prerequisites:
To edit an iteration:
{{< history >}}
{{< /history >}}
Prerequisites:
To delete an iteration:
You can track the progress of an iteration by reviewing iteration reports. An iteration report displays a list of all the issues assigned to an iteration and their status.
The report also shows a breakdown of total issues in an iteration. Open iteration reports show a summary of completed, unstarted, and in-progress issues. Closed iteration reports show the total number of issues completed by the due date.
To view an iteration report:
The iteration report includes burndown and burnup charts, similar to how they appear when viewing a milestone:
View burndown and burnup charts for iterations created for a group in any of its subgroups or projects. When you do this, the charts only count the issues that belong to the subgroup or project.
For example, suppose a group has two projects named Project 1 and Project 2.
Each project has a single issue assigned to the same iteration from the group.
An iteration report generated for the group shows issue counts for all the group's projects:
An iteration report generated for Project 1 shows only issues that belong to this project:
Group the list of issues by label to view issues that belong to your team, and get a more accurate understanding of scope attributable to each label.
To group issues by label: