Value stream analytics

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. 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.

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, value streams cannot be managed.

In Standard Edition 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.

“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 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 period of the report selects the items of a stage by date: for a saved value stream, by the date of the end event; for the built-in stream, by the date the issue or merge request was created.

Lifecycle metrics

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

• “Lead time” — the median time, in days, from the creation of an issue to its closing;
• “Cycle time” — the median time, in days, from the first commit that mentions an issue to the closing of that issue;
• “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;
• “Deploys” — the number of successful deployments to environments with the production deployment tier finished within the period; on the group report, across the projects of the group.

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. A day on which the stage finished nothing is drawn as a dashed line named “No data” between the neighbouring days. 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 period in which the stage finished nothing shows “This stage finished nothing in this range”.

Both charts show the average, and the tiles and the stage table show the median: one item with an unusually long duration shifts a point of the chart.

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 or, on the project report, the labels of the project and of its groups; 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”.

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 is paged. On the group report, each row also names the project of the item.

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 user who cannot read the items of the stage, for example the jobs of a stage measured by build events, sees “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 period is limited to 180 days. The period is kept in the address as the created_after and created_before parameters.

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

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

The bar offers the match by value only. To exclude a value instead, add the filter to the address of the page in the not form, for example not[author_username]=<USER>; the report then shows everything that does not match the value.

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 saved, the job walks its stages at once. Afterwards it runs every 10 minutes and reads the events that have appeared since the previous run. While the first walk of a stage is in progress, the page shows “The data of this report is still being collected, so it covers part of the history so far.” Once the first walk is finished, the page shows “Data as of ” instead, and the icon next to it shows “Next update expected ”. Neither line is shown while no walk has run and none is in progress.

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 first stream of the list.

“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: the form stops adding stages at “A value stream holds at most 15 stages.”, and a stream without stages is refused with “A value stream must have at least one stage”. The name of a stage of your own cannot repeat the name of a built-in stage or 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.
• 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.

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 answer with 404;
• 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 and the “Filter results” bar work as described in Period and filters, and the stage table as described in Stage table.