Maintenances
A maintenance represents planned work that may affect service availability. Unlike incidents, which describe unexpected disruptions, maintenances let you inform your customers ahead of time about scheduled changes — database migrations, infrastructure upgrades, certificate rotations, or anything else that could temporarily degrade service.
The core idea is simple: create a maintenance entry in the Dashboard, announce it on your status page, keep customers updated as work progresses, and close it when everything is stable again.
When to use a maintenance instead of an incident
If the work is planned and the timing is known in advance, use a maintenance. This gives your customers a heads-up and sets the expectation that any disruption is temporary and intentional. If something breaks unexpectedly, use an incident instead.
There is a grey area when planned work causes unexpected side effects. In that case, it is perfectly reasonable to have both a maintenance for the planned window and an incident for the unexpected issue. Incido handles this gracefully — maintenance can even suppress related incidents automatically if you configure it to do so (more on that below).
The maintenance lifecycle
Every maintenance moves through a series of stages. Understanding these stages is important because each transition can trigger visible changes on your public status page and notifications to your subscribers.
Draft is the starting point. A maintenance in Draft is only visible to operators in the Dashboard. Nothing is published, no notifications are sent. Use this stage to prepare the entry, write your customer-facing summary, select affected components, and configure automation before anyone outside your team sees it.
Scheduled is the announcement stage. When you transition a maintenance to Scheduled, it becomes visible on your public status pages. This is the moment your customers learn that work is coming. The planned start and end times, the affected components, and your summary all appear on the public maintenance list and detail page. Most teams send subscriber notifications at this point so that affected users can plan accordingly.
In Progress means work has started. The public status page reflects that the maintenance is actively underway through the maintenance timeline, ongoing indicators, and per-day history where you show them. Expected impact on each affected component describes what you anticipate for communication and incident suppression; it does not automatically change each catalog component’s health badge to that severity—live component health on the status page follows incidents (and monitors where configured), not maintenance start alone. If you enabled auto-start, the transition to In Progress happens automatically when the planned start time arrives — otherwise, an operator transitions it manually from the Dashboard.
Post Maintenance signals that the implementation work is done but the team is still verifying stability. This is a useful intermediate state: it tells customers that the disruptive phase is over while giving your team breathing room to monitor before declaring everything complete. When you reach Post Maintenance, this maintenance’s workflow impact on affected components is finished and maintenance intervals close as designed. What customers see on the status page can still be non-operational if an incident affects the same component. In the common case where no incident is open, component rows stay at the incident-derived health you already had (typically Operational).
Closed is the terminal state. No further transitions or updates are possible. The maintenance remains visible in historical views on the public status page, but it is no longer active.
You do not have to move through every stage sequentially. The Dashboard allows you to skip stages when the situation calls for it — for example, moving directly from Scheduled to Closed if planned work is cancelled, or from Draft to In Progress if you need to start immediately without a public scheduling announcement.
Creating a maintenance
Open the Maintenances section in the Dashboard and create a new entry. You will need to provide:
A title that clearly describes the work — this is what customers see first, so "Database migration — brief read-only period expected" is far more helpful than "Maintenance #47".
A customer-facing summary that explains what is happening, why, and what impact to expect. Write this for the people who depend on your service, not for your engineering team. Be specific about expected impact and duration.
An internal summary that captures context your team needs but customers should not see — runbook links, rollback plans, or escalation contacts.
Planned start and end times that define the maintenance window. These times drive the public display and, if you enable automation, the automatic start and end transitions.
Affected components that tell customers which parts of your service are involved. Each component can have a configured expected impact level (Operational, Degraded Performance, Partial Outage, or Full Outage) for planning, suppression rules, and how strongly ongoing maintenance surfaces in header ordering—not for automatically flipping the catalog component’s live health badge when maintenance starts.
Tags and metadata for internal organization — filtering, reporting, or integration with external systems.
If you create maintenances through the API or another automated path that uses the same create contract, you must supply a deduplication key: a short lowercase identifier using letters, numbers, and dashes, within the product’s length limits. When a create request uses a key that matches an existing maintenance in your organization that is still in Draft, Scheduled, or In Progress, Incido returns that existing maintenance instead of creating a duplicate—so retries and duplicate callbacks converge on one record. After that maintenance has finished that part of its lifecycle (for example once it is Closed), you may reuse the same key for a new maintenance. The Integrations and automation guide situates this pattern alongside incident deduplication and monitoring.
After saving, the maintenance starts in Draft and is only visible to your team.
Automation settings
Incido can automate two key transitions so that your maintenance window runs hands-free if everything goes according to plan.
Auto-start transitions the maintenance to In Progress when the planned start time arrives. This is useful for overnight maintenance windows or work that begins at a precise time without operator intervention. You can configure a grace period that delays the automatic transition by a set number of minutes — helpful when your deployment pipeline might run slightly behind schedule.
Auto-end transitions the maintenance to Post Maintenance when the planned end time arrives. The same grace period option is available. This does not close the maintenance; it moves it to the verification stage so your team can confirm stability before final closure.
If automation does not trigger as expected, check that the planned times are set correctly and that the grace period has not pushed the transition into the future. You can always transition manually at any time — automation is a convenience, not a lock.
Incident suppression
When your team knows that planned work will cause alerts, you probably do not want those alerts to generate customer-facing incidents. Maintenance supports an incident suppression mode that handles this automatically.
When suppression is enabled and the maintenance is In Progress, Incido evaluates every new incident that shares affected components with the maintenance. If the incident's impact does not exceed the expected impact you configured for those components, the incident is suppressed — it is created with a suppression status instead of triggering the normal incident workflow and customer notifications.
There are situations where suppression does not apply, even when enabled. If the incident's impact is worse than what the maintenance anticipated (for example, a Full Outage during a maintenance that only expected Degraded Performance), the incident goes through the normal workflow because it represents an unexpected escalation that customers should know about. Similarly, incidents with an Under Investigation impact are never suppressed because their severity is not yet determined.
Every suppression decision is recorded with a reason, so you can review after the fact why a particular incident was or was not suppressed. When the maintenance ends, any incidents that are still in the suppressed status are automatically moved to triage so your team can review them.
Publishing updates during maintenance
Throughout the maintenance lifecycle, you can publish updates that appear on the public timeline. Every published update is timestamped in that timeline, giving customers a chronological narrative of how the work is progressing. Message-only updates appear as their own Update entries, while an update that also changes the public maintenance status is folded into the same milestone row so customers can immediately connect the explanation to the stage change.
When publishing an update, you choose whether to notify subscribers. Not every update warrants a notification — a minor progress note might not need to ping everyone, but a transition to In Progress or an unexpected delay absolutely should. Use your judgment: notifications build trust when they carry meaningful information, but erode it when they become noise.
Write updates from the customer's perspective. Lead with what they are experiencing right now, explain what changed since the last update, and set expectations for when they will hear from you next. Avoid internal jargon and implementation details that do not help someone waiting for their service to come back.
The Dashboard also supports internal comments that are visible only to your team. Use these for coordination — tagging colleagues, noting decisions, or linking to internal runbooks — without cluttering the public timeline.
When you mention a teammate in an internal maintenance comment, Incido sends that person an email notification after the comment is saved. The email identifies who wrote the comment, includes the full sanitized comment content, and provides a direct button to the maintenance detail page in the Dashboard. The subject uses the maintenance title (Maintenance: {title}), and email thread headers are set so repeated mention emails for the same maintenance can group together in most mail clients. This keeps responders aligned even if they are not actively watching the maintenance page.
What changes on the public frontend
Every action you take in the Dashboard can affect what appears on your public status page. Here is what changes at each stage:
Statuses control more than workflow. Each maintenance status also carries its own customer-facing public label, public color, and public icon. That lets you keep an internal status such as Reviewing for operators while still showing Completed publicly if that is the clearest message for customers. The public timeline and badges always use those status-owned presentation fields rather than the raw internal status name.
When a maintenance moves to Scheduled, it appears on the public maintenance list with its title, customer-facing summary, planned start and end times, affected components, and the public badge defined by that status. Customers visiting your status page can see that work is coming and plan accordingly.
When it moves to In Progress, the status page reflects that work is actively underway. Component health rows reflect incident (and monitor) impact; maintenance visibility comes from maintenance listings, ongoing markers, and history strips—not from rewriting catalog status from expected impact alone. The wording customers see at that moment comes from the status's public presentation, so you can choose whether that reads as Started, Underway, or another phrase that fits your communication style.
When it moves to Post Maintenance, this maintenance’s active window ends for affected components; the public timeline shows the recovery wording defined on that status. Component rows stay aligned with incidents; without an open incident, health typically remains Operational. Historical milestones use the current public presentation configuration, so if you later refine how that status should appear publicly, old maintenance timelines pick up the new label, color, and icon as well.
When it reaches Closed, the maintenance is archived. It remains accessible in the maintenance history on the status page, but it no longer drives active maintenance indicators for that record.
Every published update appears on the maintenance detail page timeline, either as its own timestamped Update entry or attached to the milestone created by the same status transition, building a complete public record of how the work was communicated.
Operational effects
Rolling availability and downtime reporting on the public status page treat planned maintenance differently from incidents. Maintenance windows are recorded in maintenance impact intervals for transparency on the per-day strip and related views; they are not the same as incident outage rows, and catalog component health is not driven by maintenance expected impact alone. Only incident impact opens outage records for metrics in the current model. If an incident overlaps planned work, the outage row can still carry a maintenance reference so the same seconds are excluded from rolling downtime the way maintenance-linked outage rows were in older data. Your rolling percentage therefore reflects unexpected unavailability more clearly than planned windows.
Subscriber notifications are sent when you explicitly enable them on an update and when the subscriber's own preferences allow it. Stage transitions that publish to status pages (like moving to Scheduled or In Progress) can also trigger notifications.
After you publish an update or transition a stage, there may be a brief delay before the change appears on the public status page. This refresh window is typically a matter of seconds. If an update does not appear after a reasonable wait, verify that it was published to the correct status page. For publication rules, see Status pages, and for subscriber scope, see Subscribers.
Troubleshooting
A published update is not showing on the status page. Confirm the update was published to the intended status page (a maintenance can be linked to multiple pages, and you may have published to the wrong one). Wait a few seconds for public page refresh. If it still does not appear, check the maintenance detail view in the Dashboard to verify the publication status.
Subscribers did not receive a notification. Check whether you enabled the notification toggle when publishing that specific update. Then verify that the subscribers in question have active subscriptions for the relevant status page and components. Subscriber preferences and channel settings can filter out notifications even when you enabled them on your side.
Auto-start or auto-end did not trigger. Verify that automation is enabled on the maintenance entry and that the planned start or end time has actually passed (accounting for any configured grace period). If the time has passed and the transition still did not happen, transition manually and review your automation and system health logs.
An incident was not suppressed during active maintenance. Suppression only applies while the maintenance is In Progress. Check that the incident's affected components overlap with the maintenance's affected components. If they do overlap, the incident's impact may have exceeded the expected impact configured on the maintenance, or the incident may have been flagged as Under Investigation — both cases bypass suppression intentionally.