Filing your first change

Overview

A change in Vigilo is anything you want a record of. Cert rotation, firewall edit, code deployment, vendor migration, password reset for a service account — if you want it auditable, approve-able, and visible to the team, it goes through the change system.

Every change moves through a fixed state machine — draft, review, approved, scheduled, in-progress, completed, failed, rolled-back. Each transition triggers events (so your webhook and your playbooks can react), writes to the audit log, and respects freeze windows, approval policies, and task gates.

Filing one takes ~90 seconds for a simple change and as long as you need for a high-risk one. The form is the same; the policy decides what's required.

Why it exists

Most teams have a change process that lives in a Google Doc and a Slack channel. It works until the day somebody bypasses it, an outage follows, and the postmortem reveals nobody can prove what was actually approved. Vigilo's change system is the audit-log-shaped artefact your post-incident review will want — and because approvals and freeze windows are mechanical (the API refuses to advance a change in violation), the policy actually fires.

Key concepts

• ChangeRequest — The top-level record. Carries title, description, risk level, type (standard, normal, emergency), planned start/end, affected assets, rollback plan, and the FSM state.
• FSM — Finite state machine. States: draft → review → approved → scheduled → in_progress → completed (happy path), with failed and rolled_back as terminal off-ramps. See Change FSM for the full diagram and guard conditions.
• Approval policy — Rule that decides who must approve a change. Can route by risk level, type, affected services, or any custom field. Multiple approvers, any-of-N, all-of-N, and CAB-required modes all supported.
• Affected assets — Hosts, services, or vendors the change touches. Drives conflict detection and freeze-window enforcement.
• Freeze window — A time block (e.g. "no prod changes during Black Friday week") that blocks transitions into scheduled or in_progress for in-scope changes. Configured in Settings → Freeze windows.
• Conflict detection — When two changes touch overlapping assets in overlapping windows, Vigilo flags them on both records. The CAB calendar visualises the overlap.
• Task gate — A change can carry a list of pre-implementation tasks; Vigilo refuses to move into in_progress until those tasks are done. Lets you encode "the runbook must be finished before we touch prod."

Common workflows

1. File a draft

Sidebar → Changes → New change. Fill in:

• Title — short, action-oriented ("Rotate api.acme.com TLS cert").
• Type — standard (pre-approved template), normal (full approval flow), emergency (expedited, post-hoc CAB review).
• Risk — low / medium / high. Drives the approval policy match.
• Planned start / end — when you intend to execute. Conflict detection runs against this window.
• Affected assets — pick from hosts, services, vendors. Use the asset picker, or paste a comma-separated list.
• Description + rollback plan — markdown supported. The rollback plan is required for medium and high risk.

Click Save draft. The change lands in state draft.

2. Submit for review

From the change detail page → Submit for review. The FSM checks the approval policy to see who must approve, creates the ApprovalStep rows, and emails / Slacks the approvers.

3. Approve (as an approver)

Sidebar → Approvals. The pending queue shows everything waiting on you. Click → review the change → Approve (with optional comment) or Request changes. The author gets notified either way.

4. Schedule

Once all required approvals are in, the change moves to approved. The author then clicks Schedule to lock the planned window — at this point Vigilo enforces freeze windows and re-runs conflict detection. If anything fails, the change goes back to approved with an explanation.

5. Execute

At the scheduled start time (or manually), click Start. State moves to in_progress. Add an execution note ("starting rotation now") which writes to the change's activity feed.

When done, click Complete — state moves to completed. If something blew up, click Roll back instead; state moves to rolled_back and an auto-generated incident link surfaces if you want to escalate.

6. Cancel

From any pre-in_progress state, Cancel. The change is preserved (it's part of the audit trail) but moves to a terminal cancelled state.

Permissions & gating

Troubleshooting

• "Submit is greyed out." — Required fields are empty (rollback plan on medium+, affected assets on emergency). Hover the button for the specific reason.
• "Approval keeps re-opening after I approve." — Policy needs multiple approvers; another one is still pending. Check the Approvals panel on the change.
• "Schedule is blocked by a freeze window." — Either move the planned window outside the freeze, or get an owner to override (audited).
• "Conflict warning on an unrelated change." — Both changes share an affected asset. Resolve by serialising them (one finishes before the other starts), narrowing the asset list, or accepting the conflict explicitly with a comment.
• "Task gate is blocking start." — The change has pre-implementation tasks that aren't done. Open the change → Tasks panel → finish them, or remove them from the gate.

Related articles

• Changes
• Approvals
• Change Advisory Board (CAB)
• Change FSM in depth
• Freeze windows