Value stream analytics

Available since 1.16.0 (EE)

The “Value stream analytics” report shows how much time issues and merge requests spend at each stage of their path, from creation to closing or merge. The report is available for a group and for a project. The report of a group covers the group, its subgroups and all their projects.

Report availability

The report of a group is available to members of the group with the “Reporter” role and above, and to users of the “Auditor” type. Members with the “Guest” or “Planner” role do not see the “Value stream analytics” item in the group menu, and the direct address answers with 404. The visibility level of the group does not extend this access: with the “Public” or “Internal” level, a user who is not a member of the group does not see the report.

The report of a project is available to members of the project with the “Guest” role and above, including those who hold that role in a parent group, and to users of the “Auditor” type. In a project with the “Public” visibility level, the report is open to any visitor, including one who has not signed in. With the “Internal” visibility level, the report is open to any signed-in user except users of the “External” type. This holds while the “Analytics” feature of the project is set to “Everyone With Access”; with “Only Project Members”, users who are not members of the project, except users of the “Auditor” type, get 404.

In a project where the “Analytics” feature is disabled, or issues and merge requests are both disabled, the menu item is absent and the direct address answers with 404. The report of its group still counts the items of a project with the “Analytics” feature disabled. When a project has issues or merge requests disabled, the group report still counts those items in the stages and the charts, but the “Lead time”, “Cycle time” and “New issues” tiles and the “Tasks by type” chart leave them out.

Creating, editing and deleting value streams is available to members with the “Reporter” role and above in the group or the project. In an archived group, an archived project and a project of an archived group, value streams cannot be managed.

In Standard Edition the report of a group is unavailable: the group menu has no item, and the direct address answers with 404. The project page opens in the form described in Project page in Standard Edition.

Viewing the report

To view the report of a group:

1. In the top bar, select “Search or go to…” and pick the group.
2. In the group menu, go to “Analyze” → “Value stream analytics”.

To view the report of a project:

1. In the top bar, select “Search or go to…” and pick the project.
2. In the project menu, go to “Analyze” → “Value stream analytics”.

The report is also available at a direct address:

The page opens on the “Overview” tile. A link that carries the stage_id parameter opens the report on that stage. The selected value stream, stage, period, filters and projects are kept in the address of the page, so a configured report can be shared as a link.

Value streams

The report is built around a value stream: a set of stages that measure the path of an issue or a merge request. The value stream list is above the filters; while no stream is selected, it reads “Select a value stream”.

A group has no built-in value stream. Until a stream is created, the page shows “Create a value stream to start viewing analytics.”; a member who can manage value streams sees the list with the “New value stream” item.

A project starts with the built-in value stream named “default”, which holds the built-in stages. Once the project has a saved value stream, the list holds the saved streams only. The built-in stream cannot be edited or deleted.

The list is ordered by name. The selected stream is kept in the address of the page as the value_stream_id parameter.

Stages

The row of tiles above the report is the navigation through the selected stream: the “Overview” tile, then one tile per stage of the stream in the order set in the stream. A hidden stage has no tile.

On the project report, a stage that the user cannot read has no tile either. In the built-in stream, a stage needs access by its name: “Issue” to issues, “Code” and “Review” to merge requests, “Test” and “Staging” to jobs; “Plan” needs access to the report only. In a saved stream, every stage, the built-in ones included, needs access to issues or to merge requests by the object of its events, and access to jobs in their place when one of its events is a build event or a deployment event of a merge request; there “Plan” needs access to issues. A member with the “Guest” role in a private project does not see the “Code” and “Review” stages; while “Project-based pipeline visibility” is on in the CI/CD settings of the project, the “Test” and “Staging” stages stay visible to such a member, and the medians of “Test” and “Staging” read “-”. With the setting off, such a member does not see “Test” and “Staging” either.

“Overview” shows the “Lifecycle metrics” tiles and the “Total time” and “Tasks by type” charts. A stage shows the “Stage time: ” chart and the table of that stage.

A stage measures the time between its start event and its end event for one issue or one merge request. An item enters the stage once it has reached the end event; an item that reached only the start event is left out. Pointing at a stage tile shows “Stage time (median)”, “Items in stage”, the note “Only items that reached their stop event.” and the events of the stage under “Start” and “Stop”.

The built-in stages and their events:

The events of the built-in stages are recorded as follows:

• “Issue first associated with a milestone or first added to a board” — the date the issue first got a milestone or, for an issue without a milestone, the date it first got a label that has a list on an issue board;
• “Issue first mentioned in a commit” — the date of the first commit whose message references the issue, for example #<ID>; a push to any branch counts, and of one push only the last 100 commits are read; when a merge request closes an issue that has no such date yet, the date is taken from the oldest of the last 100 commits of the merge request;
• the start of “Code” — for a merge request that closes an issue, for example with Closes #<ID> in its description, the first mention of that issue in a commit; for any other merge request, the date of its first commit;
• “Merge request first deployed to production” — the end of the first successful deployment of the target branch of the merged request to a production environment, an environment of the production deployment tier; the tier is set as described in Protected environments; “Issue first deployed to production” takes the same moment from the merge request that closes the issue.

Without deployments to a production environment, “Staging” has no items.

The period of the report selects the items of a stage by the date of the end event, for a saved value stream and for the built-in stream: an item is counted in the period in which it finished the stage, whenever it was created.

Lifecycle metrics

The “Lifecycle metrics” row is shown on “Overview” and is narrowed by the period and, except “Commits” and “Deploys”, by the filters of the page:

• “Lead time” — the median time, in days, from the creation of an issue to its closing, for the issues closed within the period;
• “Cycle time” — the median time, in days, from the first commit that mentions an issue to the closing of that issue, for the issues closed within the period;
• “New issues” — the number of issues created within the period;
• “Commits” — the number of commits on the default branch within the period; the tile is shown on the project report only, to members of the project with the “Reporter” role and above;
• “Deploys” — the number of successful deployments to production environments finished within the period; on the group report, across the projects of the group, narrowed by the project selection.

The medians are counted at the moment the page opens, from the issues themselves, whichever value stream is selected. A value is rounded to one decimal place. The period of the tiles runs to the end of its last day, so the work of the current day is counted.

Charts

The “Total time” chart is shown on “Overview”: one area per stage of the selected stream, stacked, with one point per day. A point is the average duration of the items that finished the stage that day; the subtitle of the chart reads “Average time each stage took, stacked into the whole cycle”. Hidden stages are left out. On a day when a stage finished nothing while other stages did, that stage adds zero to the stack, and its tooltip row reads “No data”. A day on which no stage finished anything is drawn as a dashed line named “No data” between the neighbouring days, at the height of the whole cycle. A period in which no stage finished anything shows “No stage finished anything in this range”.

The “Stage time: ” chart replaces it while a stage is selected: the same points, named “Average time”, for that stage alone. A day on which the stage finished nothing is drawn as “No data”, whatever the other stages of the stream measured that day. A period in which the stage finished nothing shows “This stage finished nothing in this range”.

Both charts show the average, so one item with an unusually long duration shifts a point of the chart. The “Lead time” and “Cycle time” tiles and the stage tile popover show the median; the stage table shows the duration of each item.

The “Tasks by type” chart is shown on “Overview”: one column per day of the period, split by label. A column counts the issues closed that day or the merge requests merged that day, by the closing or the merge date. The chart is set up from the “Labels (15 max)” list in its header:

• the list offers the labels of the group and of its parent groups or, on the project report, the labels of the project and of its groups, at most 50 at a time; the field at the top of the list searches by name;
• the report opens with the first 10 labels in alphabetical order; a selection of more than 15 labels is refused with “Only 15 labels can be shown at a time.”;
• the “Show” switch under the list picks “Issues” or “Merge requests”.

An item that carries several selected labels is counted under each of them. The “Label” filter of the page does not apply to this chart. A period with no closed or merged items that carry the selected labels shows “No labelled work was finished in this range”. With all labels removed from the list, the chart shows “Select the labels to split the work by”.

Stage table

The table of the selected stage is shown under the “Stage time: ” chart. Its columns:

The table is sorted by “Last event” or “Duration” and shows 50 rows per page; selecting another stage returns it to the first page. On the group report, the reference of each item starts with the path of its project, for example <GROUP>/<PROJECT>#12.

A stage without items in the period, for the current filters, shows “There are 0 items to show in this stage, for these filters, within this time range.” A value stream none of whose stages the user can read shows “You need permission.”

Period and filters

The “Date range” list above the report sets the period: “Last week”, “Last 30 days”, “Last 90 days”, “Last 180 days” or “Custom”, which opens the “From” and “To” date pickers. The report opens on the last 30 days, including today. The days of the period are calendar days in UTC: the default period and the presets end with the current day in UTC, and the chart tooltips show the dates in UTC. In the date pickers the period is limited to 180 days, both ends included; in the address the last day may be up to 180 days after the first, so a period of 181 days is accepted there. A period of one day is picked by selecting the same day in “From” and then in “To”, for any day except today; a period of today alone is set through the address only. The period is kept in the address as the created_after and created_before parameters.

When a new “From” date is not earlier than the “To” date already picked or makes the period longer than 180 days, the “To” date is cleared and its calendar opens. Until a new end date is picked, the caption next to the fields reads “Select an end date”, and the report keeps the previous period.

On the report of a group or a project, a period in the address whose last day is more than 180 days after the first or that starts after it ends is replaced by the last 30 days, with the message “The given date range is larger than 180 days” or “The start date is after the end date”. The selected stream and filters are kept.

The “Filter results” bar narrows the tiles, the charts and the table together, except the “Commits” and “Deploys” tiles:

• “Milestone” — one milestone;
• “Label” — one or several labels;
• “Author” — one author;
• “Assignee” — one or several assignees.

Each filter takes the “=” operator (“is”) or the “!=” operator (“is not one of”). With “!=”, the report shows everything that does not match the value. In the address, an exclusion is kept in the not form, for example not[author_username]=<USER>.

On the group report, the “Select projects” list narrows the report to one or several projects of the group and its subgroups. The selection is kept in the address as the project_ids[] parameters.

Data freshness

A saved value stream is measured from stage events that a background job writes in advance; the built-in stream is measured from the issues and merge requests themselves at the moment of the request.

After a value stream is created, the job walks its stages at once; a stage added to a saved stream is walked by the next pass. Afterwards, every 10 to 20 minutes, it reads the events that have appeared in the group or the project since its previous pass. While the first walk of any saved value stream of the group, its subgroups and their projects, or of the project, is in progress, every stream of that report shows “The data of this report is still being collected, so it covers part of the history so far.”, and none of them shows the time of the data. Once the first walk is finished, the page shows “Data as of ” instead, with the time of the last pass over the hierarchy of the top-level group, and the icon next to it shows “Next update expected ”. Neither line is shown while no walk has run and none is in progress, and neither is shown for the built-in stream.

Changing the events or a label of a saved stage starts the walk of that stage again from the beginning, and the page shows the data collection message until the walk finishes. When another stage of the same group or project already measures the same pair of events with the same labels and has finished its walk, the data is shown at once. Renaming, moving and hiding a stage do not start a walk.

The “Lead time” tile is counted at the moment the page opens, and a saved stage from “Issue created” to “Issue closed” is read from the events of the last pass: for the issues closed since that pass, the two can show different values until the next pass.

After a project is moved to another group, a background job moves its items from the saved value streams of the group it left to the saved value streams of its new group and walks the stages of the new group and of its parent groups for the project. A project moved to a personal namespace keeps its items in the saved value streams of the group it left. The “Lifecycle metrics” tiles count the project in its new group at once.

Creating a value stream

To create a value stream:

1. Open the report of the group or the project.
2. In the value stream list, select “New value stream”. The item is under the divider at the end of the list.
3. In “Name”, enter the name of the stream: from 3 to 100 characters, unique within the group or the project.
4. Arrange the stages in “Stages”. The form opens with the built-in stages in their order. A built-in stage is moved with “Move up” and “Move down” and taken off the report with “Hide stage”, which marks it “Hidden”; “Show stage” returns it. A built-in stage keeps its events and cannot be removed.
5. To add a stage of your own, select “Add a stage” and fill in “Stage name”, “Start event” and “End event”. For a label event, pick the label in “Start event label” or “End event label”. “Remove stage” removes the stage from the form.
6. Select “Save value stream”. The page returns to the report, which opens on the stream just saved.

“Restore defaults” replaces the stage list of the form with the built-in stages in their order.

A value stream holds from 1 to 15 stages. A value stream cannot be named “default” in any letter case. The name of a stage of your own cannot repeat the name of a built-in stage in any letter case, or the name of another stage of the stream. A group or a project holds up to 50 value streams.

The form is also available at a direct address:

Stage events

A stage of your own opens with an event of an issue or of a merge request and closes with another event of the same object; an issue event and a merge request event cannot be paired. The “End event” list offers the events that pair with the chosen start event.

Issue events:

• “Issue created”;
• “Issue first associated with a milestone”;
• “Issue first added to a board”;
• “Issue first assigned”;
• “Issue first mentioned in a commit”;
• “Issue label was added”;
• “Issue label was removed”;
• “Issue last modified”;
• “Issue closed”;
• “Issue first deployed to production”.

Merge request events:

• “Merge request created”;
• “Merge request first committed”;
• “Merge request first assigned”;
• “Merge request reviewer first assigned”;
• “Merge request label was added”;
• “Merge request label was removed”;
• “Merge request last build started”;
• “Merge request last build finished”;
• “Merge request last approved”;
• “Merge request last modified”;
• “Merge request merged”;
• “Merge request closed”;
• “Merge request first deployed to production”.

The pairs are limited to those that can be read forward in time:

• “Issue created” and “Merge request created” only open a stage; “Issue first deployed to production” and “Merge request first deployed to production” only close one and are absent from the “Start event” list.
• A stage opened by “Merge request merged” closes only with “Merge request first deployed to production”, “Merge request label was added”, “Merge request label was removed” or “Merge request last modified”: the other events of a merge request happen before its merge.
• An event about the first occurrence (“Issue first assigned”, “Issue first associated with a milestone”, “Merge request first committed”) does not close a stage opened by an event about the last occurrence (“Issue closed”, “Merge request last approved”, “Issue label was removed”), because the first occurrence is earlier than the last one.
• “Merge request first committed” does not close a stage opened by “Merge request created”: the first commit of a merge request is earlier than the request itself. “Merge request last build started” does not close a stage opened by “Merge request last build finished”.
• “Issue label was added”, “Issue label was removed”, “Merge request label was added” and “Merge request label was removed” take a label each, so a label event can open and close the same stage: the stage then measures the time from one label to another.

A label event reads the history of its label on the item: “label was added” is the first time the label was put on, “label was removed” is the last time it was taken off. With the label added at 09:00, removed at 10:00, added again at 12:00 and removed at 14:00, a stage from “Issue label was added” to “Issue label was removed” with that label measures 5 hours. A group value stream takes a label of the group or of its parent groups; a project value stream takes a label of the project or of its groups. A project in a personal namespace has no group, so its value streams cannot use label events.

For example, to measure how long a merge request waits between the test environment and production, put the workflow::staging label on the merge request when it is deployed to the test environment and the workflow::production label when it is deployed to the production environment, by hand or from a CI/CD job through the API. Then add a stage that opens with “Merge request label was added” and the workflow::staging label and closes with “Merge request label was added” and the workflow::production label.

Editing a value stream

To edit a saved value stream:

1. In the value stream list, select the stream.
2. Select “Edit” next to the list.
3. Change the name and the stages the way they are set in Creating a value stream. A stage taken off the form is removed from the stream on saving.
4. Select “Save value stream”.

The “Edit” button is shown to a member who can manage value streams, and only while a saved stream is selected.

Deleting a value stream

To delete a saved value stream:

1. In the value stream list, select the stream.
2. In the list, under the divider, select “Delete ”, where <NAME> is the name of the selected stream.
3. In the “Delete ?” dialog, select “Delete”. The dialog reads “The value stream and its stages are removed. The activity they measured is not.”

After the deletion, the list is read again and its first stream is selected. On a project, once the last saved stream is deleted, the built-in stream “default” returns to the list.

Project page in Standard Edition

In Standard Edition the project page opens without the additions described above:

• the report holds the built-in stream “default” and its built-in stages; there is no value stream list, and the form addresses are unavailable;
• the “Lifecycle metrics” row holds “New issues”, “Commits” and “Deploys”; “Lead time” and “Cycle time” are absent;
• the “Total time”, “Stage time: ” and “Tasks by type” charts and the data freshness line are absent;
• the “Date range” list sets the period, and items are selected by the creation date of the issue or the merge request;
• the “Filter results” bar offers only the “=” operator, and the “New issues” tile is narrowed by labels only;
• the stage table works as described in Stage table.