Maintenance Windows

Maintenance windows let you schedule planned downtime so monitors don’t trigger incidents or fire alerts during expected outages. Use them for deployments, infrastructure upgrades, database migrations, or any period where failures are expected.

Define this in code. Manage maintenance windows as part of your monitoring-as-code workflow: YAML format · Terraform · CI/CD patterns

How maintenance windows work

When a maintenance window is active:

Alert suppression — No notifications are sent for the covered monitors (when suppressAlerts is enabled)
Incident tagging — Any incidents created during the window get severity MAINTENANCE
Monitoring continues — Checks still run, and results are still recorded for historical data

Maintenance windows do not pause monitoring — they suppress the noise from expected failures while preserving your check result history.

Creating a maintenance window

devhelm maintenance-windows create \
  --monitor-id <monitor-id> \
  --starts-at "2026-04-15T02:00:00Z" \
  --ends-at "2026-04-15T04:00:00Z" \
  --reason "Database migration"

Request fields

Field	Type	Required	Description
`monitorId`	UUID	No	Monitor to cover; omit for organization-wide
`startsAt`	datetime	Yes	Scheduled start in ISO 8601 format
`endsAt`	datetime	Yes	Scheduled end in ISO 8601 format
`reason`	string	No	Human-readable description
`repeatRule`	string	No	iCal RRULE for recurring windows (max 100 chars)
`suppressAlerts`	boolean	No	Whether to suppress alerts (default: `true`)

Omit monitorId to create an organization-wide maintenance window that covers all monitors.

Recurring maintenance

Use the repeatRule field with an iCal RRULE to schedule recurring windows:

{
  "startsAt": "2026-04-15T02:00:00Z",
  "endsAt": "2026-04-15T04:00:00Z",
  "repeatRule": "FREQ=WEEKLY;BYDAY=TU",
  "reason": "Weekly maintenance window"
}

Common patterns:

RRULE	Schedule
`FREQ=WEEKLY;BYDAY=TU`	Every Tuesday
`FREQ=MONTHLY;BYMONTHDAY=1`	First day of each month
`FREQ=WEEKLY;BYDAY=SA;INTERVAL=2`	Every other Saturday

Listing maintenance windows

devhelm maintenance-windows list
devhelm maintenance-windows list --filter active
devhelm maintenance-windows list --monitor-id <monitor-id>

Filter values:

Filter	Returns
`active`	Currently running maintenance windows
`upcoming`	Scheduled future windows

Updating a maintenance window

devhelm maintenance-windows update <window-id> \
  --ends-at "2026-04-15T05:00:00Z" \
  --reason "Extended — migration taking longer"

Deleting a maintenance window

devhelm maintenance-windows delete <window-id>