doc/user/okrs.md
{{< details >}}
{{< /details >}}
{{< history >}}
okrs_mvc. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
Objectives and key results (OKRs) are a framework for setting and tracking goals that are aligned with your organization's overall strategy and vision.
The objective and the key result in GitLab share many features. In the documentation, the term OKRs refers to both objectives and key results.
OKRs are a type of work item, a step towards default issue types in GitLab. For the roadmap of migrating issues and epics to work items and adding custom work item types, see epic 6033 or the Plan direction page.
Use objectives and key results to align your workforce towards common goals and track the progress. Set a big goal with an objective and use child objectives and key results to measure the big goal's completion.
Objectives are aspirational goals to be achieved and define what you're aiming to do. They show how an individual's, team's, or department's work impacts overall direction of the organization by connecting their work to overall company strategy.
Key results are measures of progress against aligned objectives. They express how you know if you have reached your goal (objective). By achieving a specific outcome (key result), you create progress for the linked objective.
To know if your OKR makes sense, you can use this sentence:
<!-- vale gitlab_base.FutureTense = NO --><!-- vale gitlab_base.FutureTense = YES -->I/we will accomplish (objective) by (date) through attaining and achieving the following metrics (key results).
To learn how to create better OKRs and how we use them at GitLab, see the Objectives and Key Results handbook page.
To create an objective:
To create a key result, add it as a child to an existing objective.
To view an objective:
Type = Objective.To view a key result:
Type = Key Result.Alternatively, you can access a key result from the Child items section in its parent's objective.
{{< history >}}
{{< /history >}}
Prerequisites:
To edit an OKR:
{{< history >}}
{{< /history >}}
If an OKR description is long, GitLab displays only part of it. To see the whole description, you must select Read more. This truncation makes it easier to find other elements on the page without scrolling through lengthy text.
To change whether descriptions are truncated:
This setting is remembered and affects all issues, tasks, epics, objectives, and key results.
{{< history >}}
{{< /history >}}
Attributes are shown in a sidebar to the right of the description when space allows. To hide the sidebar and increase space for the description:
This setting is remembered and affects all issues, tasks, epics, objectives, and key results.
To show the sidebar again:
{{< history >}}
work_items_mvc_2. Disabled by default.work_items_mvc in GitLab 15.8. Disabled by default.work_items_mvc to work_items_beta in GitLab 16.10.work_items_beta removed in GitLab 18.6.{{< /history >}}
Prerequisites:
You can view all the system notes related to the OKR. By default they are sorted by Oldest first. You can always change the sorting order to Newest first, which is remembered across sessions.
You can add comments and reply to threads in OKRs.
{{< history >}}
{{< /history >}}
To show who is responsible for an OKR, you can assign users to it.
Prerequisites:
To change the assignee on an OKR:
{{< history >}}
{{< /history >}}
Prerequisites:
Use labels to organize OKRs among teams.
To add labels to an OKR:
{{< history >}}
{{< /history >}}
You can add an objective to a milestone. You can see the milestone title when you view an objective.
Prerequisites:
To add an objective to a milestone:
{{< history >}}
{{< /history >}}
Show how much of the work needed to achieve an objective is finished.
You can set progress manually on objectives and key results.
When you enter progress for a child item, progress of all parent items in the hierarchy is updated to the average of the child items' progress. You can override progress at any level and enter a value manually, but when a child item's progress value is updated, the automation updates all parents again to show the average.
Prerequisites:
To set progress of an objective or key result:
Type = Objective or Type = Key Result and select your item.{{< history >}}
{{< /history >}}
To better track the risk in meeting your goals, you can assign a health status to each objective and key result. You can use health status to signal to others in your organization whether OKRs are progressing as planned or need attention to stay on schedule.
Prerequisites:
To set health status of an OKR:
{{< history >}}
/promote_to introduced in GitLab 16.1.{{< /history >}}
Prerequisites:
To promote a key result:
Alternatively, use the /promote_to objective quick action.
{{< history >}}
work_items_beta. Disabled by default.okrs_mvc. For current flag state, see the top of this page.{{< /history >}}
Convert an objective or key result into another item type, such as:
[!warning] Changing the type might result in data loss if the target type does not support all fields from the original type.
Prerequisites:
To convert an OKR into another item type:
Alternatively, you can use the /type quick action, followed
by issue, task, objective or key result in a comment.
{{< history >}}
{{< /history >}}
To refer to an objective or key result elsewhere in GitLab, you can use its full URL or a short reference, which looks like
namespace/project-name#123, where namespace is either a group or a username.
To copy the objective or key result reference to your clipboard:
You can now paste the reference into another description or comment.
Read more about objective or key result references in GitLab-Flavored Markdown.
{{< history >}}
{{< /history >}}
You can create a comment in an objective or key result by sending an email. Sending an email to this address creates a comment that contains the email body.
For more information about creating comments by sending an email and the necessary configuration, see Reply to a comment by sending email.
To copy the objective's or key result's email address:
{{< history >}}
{{< /history >}}
When an OKR is achieved, you can close it. The OKR is marked as closed but is not deleted.
Prerequisites:
To close an OKR:
You can reopen a closed OKR the same way.
In GitLab, objectives are similar to key results. In your workflow, use key results to measure the goal described in the objective.
You can add child objectives to a total of 9 levels. An objective can have up to 100 child OKRs. Key results are children of objectives and cannot have children items themselves.
Child objectives and key results are available in the Child items section below an objective's description.
{{< history >}}
{{< /history >}}
Prerequisites:
To add a new objective to an objective:
To add an existing objective to an objective:
In an objective, in the Child items section, select Add and then select Existing objective.
Search for the desired objective by entering part of its title, then selecting the desired match.
To add multiple objectives, repeat this step.
Select Add objective.
{{< history >}}
{{< /history >}}
Prerequisites:
To add a new key result to an objective:
To add an existing key result to an objective:
In an objective, in the Child items section, select Add and then select Existing key result.
Search for the desired OKR by entering part of its title, then selecting the desired match.
To add multiple objectives, repeat this step.
Select Add key result.
{{< history >}}
{{< /history >}}
Prerequisites:
By default, child OKRs are ordered by creation date. To reorder them, drag them around.
{{< history >}}
okr_checkin_reminders. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
Schedule check-in reminders to remind your team to provide status updates on the key results you care about. Reminders are sent to all assignees of descendant objects and key results as email notifications and to-do items. Users can't unsubscribe from the email notifications, but check-in reminders can be turned off. Reminders are sent on Tuesdays.
Prerequisites:
To schedule a recurring reminder for an objective, in a new comment use the
/checkin_reminder quick action.
{{< history >}}
{{< /history >}}
Prerequisites:
To set an objective as a parent of an OKR:
To remove the parent of the objective or key result, next to Parent, select the dropdown list and then select Unassign.
{{< history >}}
{{< /history >}}
Confidential OKRs are OKRs visible only to members of a project with sufficient permissions. You can use confidential OKRs to keep security vulnerabilities private or prevent surprises from leaking out.
{{< history >}}
{{< /history >}}
By default, OKRs are public. You can make an OKR confidential when you create or edit it.
When you create a new objective, a checkbox right below the text area is available to mark the OKR as confidential.
Select that checkbox and then select Create objective or Create key result to create the OKR.
Prerequisites:
To change the confidentiality of an existing OKR:
{{< history >}}
{{< /history >}}
When an OKR is made confidential, only users with the Planner, Reporter, Developer, Maintainer, or Owner role for the project have access to the OKR. Users with Guest or Minimal roles can't access the OKR even if they were actively participating before the change.
However, a user with the Guest role can create confidential OKRs, but can only view the ones that they created themselves.
Users with the Guest role or non-members can read the confidential OKR if they are assigned to the OKR. When a Guest user or non-member is unassigned from a confidential OKR, they can no longer view it.
Confidential OKRs are hidden in search results for users without the necessary permissions.
Confidential OKRs are visually different from regular OKRs in a few ways. Wherever OKRs are listed, you can see the confidential ({{< icon name="eye-slash" >}}) icon next to the OKRs that are marked as confidential.
If you don't have enough permissions, you cannot see confidential OKRs at all.
Likewise, while inside the OKR, you can see the confidential ({{< icon name="eye-slash" >}}) icon right next to the breadcrumbs.
Every change from regular to confidential and vice versa, is indicated by a system note in the OKR's comments, for example:
{{< history >}}
work_items_beta. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
You can prevent public comments in an OKR. When you do, only project members can add and edit comments.
Prerequisites:
To lock an OKR:
A system note is added to the page details.
If an OKR is closed with a locked discussion, then you cannot reopen it until the discussion is unlocked.
{{< history >}}
linked_work_items. Enabled by default.linked_work_items removed.{{< /history >}}
Linked items are a bi-directional relationship and appear in a block below the Child objectives and key results. You can link an objective, key result, or a task in the same project with each other.
The relationship only shows up in the UI if the user can see both items.
Prerequisites:
To link an item to an objective or key result:
When you have finished adding all linked items, you can see them categorized so their relationships can be better understood visually.
Prerequisites:
In the Linked items section of an objective or key result, next to each item, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then select Remove.
Due to the bi-directional relationship, the relationship no longer appears in either item.