Guides4 min read
Schedule service maintenance windows
Hold new alerts for one or more services during planned work, repeat windows on a schedule, and decide what happens to held alerts when the window ends.
New in 2.2.0. A maintenance window tells OpsKnight that planned work is under way on one or more services, so alerts that the work causes do not page anyone.
Before you begin
- You need permission to change every service the window covers (the same permission as editing the service).
- Know the start time, the expected duration, and which services the work touches.
- If customers should see the work, have a status page that shows those services.
Open the feature
Open Services, select a service, and choose the Maintenance tab. Services in an active window show an In maintenance badge in the service list and on the service page.
Configure a window
- Select Schedule maintenance.
- Enter a Title and, optionally, a Description.
- Under Repeat, keep Does not repeat for one-off work, or choose Daily, Weekly (pick the days), or Monthly (pick the day; it is moved to the last day of shorter months). Set how often it repeats, the start date and time, the Time zone, and an optional end date.
- For one-off work, choose Start now or a start time, then a Duration (30 minutes to 24 hours).
- Select the services. One window can cover several services.
- Under When the window ends, choose:
- Page for alerts that are still firing (recommended): held incidents whose alerts are still open are released and page normally.
- Auto-resolve every held incident.
- Optionally turn on Show on status pages and notify their subscribers to publish a maintenance announcement on each status page that shows the services.
- Select Schedule, Start maintenance, or Schedule recurring.
How a maintenance window works
- While a window is active, a new alert for a covered service opens a Suppressed incident linked to the window. Nobody is paged, the SLA clock is paused, and Runbooks are not started.
- Incidents that were already open keep escalating. Incidents a person creates by hand are never held. A resolve event from the source still closes a held incident.
- Held incidents are hidden from the default incident list; the Suppressed filter shows them. The incident page shows Held by maintenance window with a link to the window.
- Whether a window is active is worked out from its start and end times, so a stalled scheduler cannot leave a service in maintenance. At the end, the scheduler releases or resolves held incidents in batches; a very large backlog finishes over several scheduler ticks.
- Recurring schedules create their occurrences up to 14 days ahead as ordinary windows. Editing, pausing, or deleting a schedule changes only upcoming occurrences.
- The same windows are available through REST API v2 (
/api/v2/maintenance-windowsand/api/v2/maintenance-schedules, scopesservices:readandservices:write) and the mobile app.
Verify the result
- Confirm the service shows In maintenance during the window.
- Send a test event to the service's integration and confirm it creates a Suppressed incident that does not page the on-call responder.
- After the window ends, confirm the held incident was released or resolved as you chose.
Change or undo it
- End now ends an active window early. It asks for confirmation, because paging resumes.
- Delete removes an upcoming window. A window that holds incidents cannot be deleted; end it instead.
- Recurring schedules can be edited, paused, resumed, or deleted from the Maintenance tab.
Troubleshooting
- An alert still paged during maintenance: the incident was already open before the window started, was created by a person, or belongs to a service the window does not cover.
- Held incidents were not released at the end: open Settings → System → Health. The Maintenance windows check reports windows that ended but were not processed, which usually means the scheduler role is not running.
- You cannot select a service: you need permission to change that service.
Next steps
Last updated for v2.2.0
Edit this page on GitHub