Skip to content

Manage incidents

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

This page collects instructions for all the things you can do with incidents or in relation to them.

Create an incident

You can create an incident manually or automatically.

Add an incident to an iteration

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

To add an incident to an iteration:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues or Monitor > Incidents, then select your incident to view it.
  3. On the right sidebar, in the Iteration section, select Edit.
  4. From the dropdown list, select the iteration to add this incident to.
  5. Select any area outside the dropdown list.

Alternatively, you can use the /iteration quick action.

From the incidents list

Prerequisites:

  • You must have at least the Reporter role for the project.

To create an incident from the incidents list:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Monitor > Incidents.
  3. Select Create incident.

From the issues list

Prerequisites:

  • You must have at least the Reporter role for the project.

To create an incident from the issues list:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues, and select New issue.
  3. From the Type dropdown list, select Incident. Only fields relevant to incidents are available on the page.
  4. Select Create issue.

From an alert

Create an incident issue when viewing an alert. The incident description is populated from the alert.

Prerequisites:

  • You must have at least the Developer role for the project.

To create an incident from an alert:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Monitor > Alerts.
  3. Select your desired alert.
  4. Select Create incident.

After an incident is created, to view it from the alert, select View incident.

When you close an incident linked to an alert, GitLab changes the alert's status to Resolved. You are then credited with the alert's status change.

Automatically, when an alert is triggered

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

In the project settings, you can turn on creating an incident automatically whenever an alert is triggered.

Using the PagerDuty webhook

You can set up a webhook with PagerDuty to automatically create a GitLab incident for each PagerDuty incident. This configuration requires you to make changes in both PagerDuty and GitLab.

Prerequisites:

  • You must have at least the Maintainer role for the project.

To set up a webhook with PagerDuty:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Monitor
  3. Expand Incidents.
  4. Select the PagerDuty integration tab.
  5. Turn on the Active toggle.
  6. Select Save integration.
  7. Copy the value of Webhook URL for use in a later step.
  8. To add the webhook URL to a PagerDuty webhook integration, follow the steps described in the PagerDuty documentation.

To confirm the integration is successful, trigger a test incident from PagerDuty to check if a GitLab incident is created from the incident.

View incidents list

To view the incidents list:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Monitor > Incidents.

To view an incident's details page, select it from the list.

Who can view an incident

Whether you can view an incident depends on the project visibility level and the incident's confidentiality status:

  • Public project and a non-confidential incident: Anyone can view the incident.
  • Private project and non-confidential incident: You must have at least the Guest role for the project.
  • Confidential incident (regardless of project visibility): You must have at least the Reporter role for the project.

Assign to a user

Assign incidents to users that are actively responding.

Prerequisites:

  • You must have at least the Reporter role for the project.

To assign a user:

  1. In an incident, on the right sidebar, next to Assignees, select Edit.
  2. From the dropdown list, select one or multiple users to add as assignees.
  3. Select any area outside the dropdown list.

Change severity

See incident list for a full description of the severity levels available.

Prerequisites:

  • You must have at least the Reporter role for the project.

To change an incident's severity:

  1. In an incident, on the right sidebar, next to Severity, select Edit.
  2. From the dropdown list, select the new severity.

You can also change the severity using the /severity quick action.

Change status

Prerequisites:

  • You must have at least the Developer role for the project.

To change the status of an incident:

  1. In an incident, on the right sidebar, next to Status, select Edit.
  2. From the dropdown list, select the new severity.

Triggered is the default status for new incidents.

As an on-call responder

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

On-call responders can respond to incident pages by changing the status.

Changing the status has the following effects:

  • To Acknowledged: limits on-call pages based on the project's escalation policy.
  • To Resolved: silences all on-call pages for the incident.
  • From Resolved to Triggered: restarts the incident escalating.

In GitLab 15.1 and earlier, changing the status of an incident created from an alert also changes the alert status. In GitLab 15.2 and later, the alert status is independent and does not change when the incident status changes.

Change escalation policy

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

Prerequisites:

  • You must have at least the Developer role for the project.

To change the escalation policy of an incident:

  1. In an incident, on the right sidebar, next to Escalation policy, select Edit.
  2. From the dropdown list, select the escalation policy.

By default, new incidents do not have an escalation policy selected.

Selecting an escalation policy changes the incident status to Triggered and begins escalating the incident to on-call responders.

In GitLab 15.1 and earlier, the escalation policy for incidents created from alerts reflects the alert's escalation policy and cannot be changed. In GitLab 15.2 and later, the incident escalation policy is independent and can be changed.

Close an incident

Prerequisites:

  • You must have at least the Reporter role for the project.

To close an incident, in the upper-right corner, select Incident actions ({ellipsis_v}) and then Close incident.

When you close an incident that is linked to an alert, the linked alert's status changes to Resolved. You are then credited with the alert's status change.

Automatically close incidents via recovery alerts

Turn on closing an incident automatically when GitLab receives a recovery alert from a HTTP or Prometheus webhook.

Prerequisites:

  • You must have at least the Maintainer role for the project.

To configure the setting:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Monitor.
  3. Expand the Incidents section.
  4. Select the Automatically close associated incident checkbox.
  5. Select Save changes.

When GitLab receives a recovery alert, it closes the associated incident. This action is recorded as a system note on the incident indicating that it was closed automatically by the GitLab Alert bot.

Delete an incident

Prerequisites:

  • You must have the Owner role for a project.

To delete an incident:

  1. In an incident, select Incident actions ({ellipsis_v}).
  2. Select Delete incident.

Alternatively:

  1. In an incident, select Edit title and description ({pencil}).
  2. Select Delete incident.

Other actions

Because incidents in GitLab are built on top of issues, they have the following actions in common: