Migrate to ilert
Move an existing on-call or status page setup onto ilert with the CLI and a AI agent — planned first.
Note: if you have trouble following this guide, your ai agent can help you with that setup as well, simply provide this link: migrate-to-ilert.md to your agent and ask for guidance.
A migration is mostly reading one API and writing another: users, schedules, escalation policies, alert sources, services, status pages. That is work an agent does well — provided it knows how the two products differ, and provided nothing is created before you have seen the plan. The CLI gives it both. The command tree covers the full ilert API, --dry-run turns any change into a plan, and the bundled skills carry the mapping knowledge that is not visible from an API spec.
Overview of the expected migration steps
Have a coding/ai agent installed on your machine e.g. claude or codex
Install and authorize ilert-cli
Grab a read-only short-term token from your current provider
Place the current provider token in a credential-proxy, env variable or file
Start a new session with your agent
Reference the current provider token origin (first prompt suggestion below)
Prompt pointing at ilert-cli and your desire to migrate from current provider (second prompt suggestion below)
Wait for agent to gather context and ilert skills and to provide a migration plan
Adjust or approve plan execution
Verify imported resources with smoke test
Rotate used current provider token
Adjust your monitoring tools to switch to the new ilert integrationKeys
Make the cut over
Before we invoke your agent, lets talk about handling your current provider's API key
To read your existing configuration, the agent needs an API key for the provider you are migrating from. How you supply that key is your decision, but we recommend never typing it into a prompt.
If you are not running your agent like claude or codex from the shell but in the UI/apps, the below guide for environment variables will not work. In this case you have to place the SOURCE_PROVIDER_API_KEY of your current provider in a file, explaining step 3 below is the same, except for reference the filename that you are using. Be sure to rotate the key immediately after the migration process is completed.
Recommended
Create a read-only key in your current provider, scoped to the minimum the migration needs, and give it a short expiry if the provider supports one.
Put it in an environment variable rather than in the conversation or a file:
Tell the agent how to reference it, instead of telling it the key:
Revoke the key in your current provider once the migration is complete.
A key pasted into a prompt should be treated as disclosed. Prompts and agent transcripts are commonly stored and sent to third-party model providers, so rotate any credential that has been entered into a chat.
Let the agent pull the playbook and ask for a plan, not a migration
The CLI ships migration playbooks as skills. The index lists what is bundled ilert skills list, including one for each on-call and status page provider we cover.
They exist because the vocabulary collides in ways that look correct and route nothing. In most other tools, one object receives events, owns the escalation policy and holds the integration keys; in ilert that is an Alert Source, while an ilert Service is a business capability people subscribe to and which routes nothing. Likewise the actionable page is an ilert Alert, whereas an ilert Incident is the coordination record a level above it. An agent that skips the playbook maps both the obvious way and hands you a topology that pages no one.
So, steer your agent into the right direction with a simple prompt:
The CLI backs that instruction up: destructive commands refuse to run unattended and exit 2 with a JSON envelope describing what they refused, so an agent should not quietly push through a change you did not approve.
Work in the order the objects depend on each other — users and teams, then schedules, then escalation policies, then alert sources and services, then status pages — and review each stage before the next. A wrong escalation policy is cheap to fix while nothing points at it yet. The skills should already guide the agent to follow the correct order for each provider.
Note that it is perfectly fine to port partial resources and their dependencies for a PoC with one or more teams first, to evaluate faster and gain confidence. Then port the rest over - to achieve that, just make sure to tell your agent when prompting the second prompt above.
Verify before you cut over
After you followed up with your agent on the plan and finished importing your resources (as well as rotating that other providers token), we recommend a quick round of verifications before cutting over.
Integration keys are new on ilert, so every emitter has to be re-pointed — that step is manual by nature and is usually what decides the cut-over date. Fire a test event at each new source and confirm it reaches the intended responders before you switch traffic over. You dont have to run this manually, ask your agent to evaluate the smoke tests with you.
Last updated
Was this helpful?