docs: document phone number normalization migration#2510
Open
docs: document phone number normalization migration#2510
Conversation
Document the new kratos migrate normalize-phone-numbers command for self-hosted (OSS and OEL) Kratos administrators. The guide explains why normalization matters, the required deploy-then-migrate rollout sequence, command flags, and how to interpret the output. Also link to the new guide from the upgrade guide so admins see it when planning a version upgrade that introduces phone normalization. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds self-hosted documentation for the new Kratos phone number normalization migration and wires it into the docs navigation/upgrade flow.
Changes:
- Add a new guide explaining the
kratos migrate normalize-phone-numbersrollout sequence, flags, output, and rollback considerations. - Update the Kratos upgrade guide to reference the new normalization guide during upgrades.
- Add the new guide to the Kratos Guides section in the docs sidebar.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
src/sidebar.ts |
Adds the new normalization guide to the Kratos “Self-Hosted > Guides” sidebar list. |
docs/kratos/guides/upgrade.mdx |
Adds an upgrade checklist step linking to the phone normalization guide. |
docs/kratos/guides/normalize-phone-numbers.mdx |
New end-to-end migration guide for phone normalization to E.164. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
hperl
changed the title
📝 WalkthroughWalkthroughAdds a new guide documenting phone number normalization and a migration CLI, and updates the upgrade guide to include a new checklist step and small formatting fixes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Admin as Admin
participant Deploy as Deploy (New Kratos)
participant Migrate as Migrator (kratos migrate)
participant DB as Database
participant Parser as phonenumbers
Admin->>Deploy: Deploy new version that normalizes on write
Deploy-->>Admin: New instance serves traffic
Admin->>Migrate: Run `kratos migrate normalize-phone-numbers`
Migrate->>DB: Scan target tables & rows (with filters)
loop per row
Migrate->>Parser: Parse phone-like value
alt parsed
Parser-->>Migrate: E.164 value
Migrate->>DB: UPDATE row (handle unique conflicts/log)
else unparsable/skip
Parser-->>Migrate: skip
end
end
Migrate-->>Admin: Summary (scanned, updated, skipped, errors)
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/kratos/guides/upgrade.mdx`:
- Around line 20-22: The inline CLI command "kratos migrate
normalize-phone-numbers" is missing its opening backtick and has a dangling
backtick; update the sentence in the upgrade guide to wrap the command in
backticks (e.g., `kratos migrate normalize-phone-numbers`) so the inline code is
properly formatted and renders correctly in the docs; verify the closing
backtick remains and preview the MDX to ensure the command is styled as inline
code.
In `@src/sidebar.ts`:
- Line 610: The sidebar entry "kratos/guides/normalize-phone-numbers" in
src/sidebar.ts is referencing a nonexistent doc id and is breaking the docs
build; fix it by either adding a doc file whose frontmatter defines the id
"kratos/guides/normalize-phone-numbers" (matching the sidebar entry) or change
the sidebar entry in src/sidebar.ts to the actual existing doc id used by the
guide (e.g., the correct id string found in the guide's frontmatter), ensuring
the id in the sidebar and the doc frontmatter match exactly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 50ee6436-99ea-402d-8b56-6e6f13f80690
📒 Files selected for processing (2)
docs/kratos/guides/upgrade.mdxsrc/sidebar.ts
hperl
changed the title
unatasha8
reviewed
Apr 15, 2026
|
|
||
| This guide is for self-hosted Kratos administrators (OSS and OEL). Ory Network customers don't need to take any action. | ||
|
|
||
| :::info |
Contributor
There was a problem hiding this comment.
Suggested change
| :::info | |
| :::important |
unatasha8
reviewed
Apr 15, 2026
|
|
||
| :::info | ||
|
|
||
| Back up your database before running the migration. |
Contributor
There was a problem hiding this comment.
Suggested change
| Back up your database before running the migration. | |
| Back up your database before running the migration. The migration doesn't store the original value, therefore there's no automatic rollback after migration. To revert, you will need to restore your backed-up database. |
unatasha8
reviewed
Apr 15, 2026
Comment on lines
+54
to
+57
| :::caution | ||
|
|
||
| Don't run the migration before deploying the new Kratos version. The previous version does exact-string matching on identifiers. | ||
| If you normalize the database first, users who type their phone number in the original (non-E.164) format won't be able to log in |
Contributor
There was a problem hiding this comment.
Move this caution to beneath Rollout sequence.
unatasha8
reviewed
Apr 15, 2026
| sidebar_label: Normalize phone numbers | ||
| --- | ||
|
|
||
| Starting with this release, Ory Kratos normalizes phone numbers to [E.164 format](https://en.wikipedia.org/wiki/E.164) when |
Contributor
There was a problem hiding this comment.
Suggested change
| Starting with this release, Ory Kratos normalizes phone numbers to [E.164 format](https://en.wikipedia.org/wiki/E.164) when | |
| Ory Kratos normalizes phone numbers to [E.164 format](https://en.wikipedia.org/wiki/E.164) when |
unatasha8
reviewed
Apr 15, 2026
Contributor
unatasha8
left a comment
unatasha8
left a comment
There was a problem hiding this comment.
Where are you planning to put normalize-phone-numbers.mdx in the sidebar? This content is a mix of 1. "how Ory Kratos normalizes phone numbers" and 2. "migrate existing phone numbers to normalized phone numbers". I'd suggest two separate articles. 1. should live in the Kratos OSS/OEL docs (remove 'starting with this release' to keep content fresh) and 2 should be with the upgrade docs. QUESTION: what happens if the customer upgrade but decides not to migrate their phone numbers. What would happen?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds documentation for the new
kratos migrate normalize-phone-numbersCLI command for self-hosted (OSS and OEL) Kratos administrators.The new guide at
docs/kratos/guides/normalize-phone-numbers.mdxexplains:--dry-run,--batch-size,-e)Also updates the upgrade guide (
docs/kratos/guides/upgrade.mdx) to link to the new guide as a step when upgrading to a version that introduces phone normalization.Ory Network customers don't need to take any action — this is for self-hosted only.
Companion to ory-corp/cloud#11283.
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit