Conversation
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
💤 Files with no reviewable changes (2)
🚧 Files skipped from review as they are similar to previous changes (3)
📝 WalkthroughWalkthroughThis PR adds a complete AsciiDoc guide for the mta-ops CLI, including master files, symlink wiring, assemblies, and topic pages covering installation, cluster access, migration stages, deployment, validation, troubleshooting, and command options. Changesmta-ops documentation guide
Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 15
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@assemblies/mta-ops-guide/assembly_validating-target-cluster-compatibility.adoc`:
- Around line 24-26: The “Next steps” label in this section uses “workflows,”
but the guide consistently refers to workloads/manifests, so update the text in
the affected next-step bullet to use the correct term. Locate the “Next steps”
content in assembly_validating-target-cluster-compatibility.adoc and replace
“Deploy the migrated workflows.” with wording that matches the rest of the
guide, keeping the same intent but using “workloads.”
In `@docs/topics/mta-ops/con_introduction-to-the-mta-ops-cli.adoc`:
- Around line 13-21: The local-disk statement is too broad because the migration
pipeline includes the deployment stage, which applies workloads to the
destination cluster. Update the wording in the introduction to scope the “output
directly to your local disk” claim to the non-deployment stages only, or
separate the deployment stage into its own note; use the stage list in the MTA
Ops CLI introduction to keep the export, transformation, application, and
validation descriptions aligned.
In `@docs/topics/mta-ops/con_local-manifest-generation.adoc`:
- Line 15: Clarify that the `--skip-cluster-scoped` flag is intended for
namespace-only, split-responsibility deployment workflows rather than “for
administrators”; update the wording in the `mta-ops` consolidated-file
description so it aligns with the rest of the guide and makes the audience
clear. Reference the `--skip-cluster-scoped` option and the surrounding
explanation of consolidated resource ordering when revising the sentence.
In `@docs/topics/mta-ops/con_mta-ops-cli-standalone-architecture.adoc`:
- Around line 11-13: The install description for the mta-ops CLI is inconsistent
with the actual procedure, which downloads a .zip archive and then extracts the
binary. Update the standalone architecture page text to describe the install
artifact as a downloadable archive rather than a direct binary, keeping the
wording aligned with the install steps for the mta-ops CLI and the mta-ops
pipeline.
In `@docs/topics/mta-ops/con_workload-deployment.adoc`:
- Line 15: The deployment procedure currently points readers to the wrong
artifact path; update the referenced output file in the surrounding deployment
instructions to use output/output.yaml consistently. Make this change in the
affected documentation section so the path matches the rest of the deployment
workflow and the guidance around applying the consolidated output artifact
remains consistent.
- Around line 11-13: The architecture description overstates that the entire
mta-ops pipeline “does not connect to the target cluster,” which conflicts with
the live validation behavior documented elsewhere. Update the wording in the
affected prose to scope the no-cluster-connection claim only to the local
artifact-generation stages, and keep the rest of the pipeline description
consistent with the validation flow described by the mta-ops pipeline docs.
In `@docs/topics/mta-ops/proc_downloading-and-extracting-the-mta-ops-cli.adoc`:
- Around line 8-17: The abstract in
proc_downloading-and-extracting-the-mta-ops-cli topic uses “binary” where the
procedure actually downloads and extracts a `.zip` archive, so update the
wording to use “archive” for consistency with the steps and the
standalone-architecture topic. Keep the rest of the procedure intact and only
adjust the abstract text near the [role="_abstract"] section so it accurately
describes downloading and extracting the archive.
In `@docs/topics/mta-ops/proc_executing-a-stateless-migration-quickstart.adoc`:
- Around line 42-46: The deploy step in the quickstart is ambiguous because the
`oc apply` command in the migration instructions relies on whatever current kube
context is active. Update the wording around the deployment step in the
stateless migration quickstart to explicitly tell the user to switch or verify
the target cluster context before running `oc apply`, and make the instruction
in the deploy section clearly refer to the target cluster using the existing
deployment step text.
In `@docs/topics/mta-ops/proc_exporting-manifests-from-the-source-cluster.adoc`:
- Around line 27-31: The example in the exporting-manifests doc uses service
account wording for the `--as` and `--as-group` flags, but these flags are for
username/group impersonation. Update the sentence and the `mta-ops export`
example near the impersonation guidance to use user/group terminology instead of
“service account-based migrations” and rename the `_service_account_name_`
placeholder accordingly while keeping the `--as` and `--as-group` references.
In `@docs/topics/mta-ops/proc_generating-ordered-manifests-locally.adoc`:
- Line 22: Fix the malformed namespace placeholder in the AsciiDoc command
example so it follows the repo’s _<name>_ convention. Update the path text in
the generated-manifests docs to use the consistent outer-underscore placeholder
format, matching other placeholder usages in this document and related examples.
In
`@docs/topics/mta-ops/proc_validating-workload-manifests-against-a-live-cluster.adoc`:
- Around line 24-56: The fenced example is mislabeled as YAML even though the
payload is JSON, so update the AsciiDoc source annotation for this sample to
JSON. Locate the code block containing the live cluster validation output and
change the language marker used with the fenced block so it matches the shown
structure and preserves correct syntax highlighting.
In `@docs/topics/mta-ops/ref_developer-and-architecture-guides.adoc`:
- Line 15: The first mention of E2E in the development guides bullet should
expand the acronym to match repo style. Update the bullet in the documented list
so it reads as end-to-end (E2E) before later shorthand use, keeping the rest of
the description unchanged.
In `@docs/topics/mta-ops/ref_mta-ops-export-command-options.adoc`:
- Line 16: Update the `--namespace` option description in the `mta-ops export`
command options table so it refers to the source namespace, not the target
namespace. Adjust the wording in the affected row to match the `export` command
behavior and keep the terminology consistent with the surrounding export docs,
using the `--namespace` / `-n` option entry as the anchor.
In `@docs/topics/mta-ops/ref_mta-ops-transform-command-options.adoc`:
- Line 19: The CLI option name in the transform command options table is
malformed: `--skip-plugin`s` reads like a typo and does not document a valid
flag. Update the documented flag in the table entry used for the transform
command options so it matches the actual CLI identifier consistently, and verify
the surrounding option name formatting in this section remains correct.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: e46f4bd8-2e03-423a-8185-e2323278af5c
📒 Files selected for processing (49)
assemblies/mta-ops-guide/assembly_configuring-cluster-access-for-migration.adocassemblies/mta-ops-guide/assembly_deploying-the-migrated-workloads.adocassemblies/mta-ops-guide/assembly_exporting-workload-manifests.adocassemblies/mta-ops-guide/assembly_generating-final-deployable-manifests.adocassemblies/mta-ops-guide/assembly_installing-the-mta-ops-cli.adocassemblies/mta-ops-guide/assembly_migrating-stateless-workloads.adocassemblies/mta-ops-guide/assembly_mta-ops-command-options.adocassemblies/mta-ops-guide/assembly_supported-migration-paths-and-api-compatibility.adocassemblies/mta-ops-guide/assembly_transforming-workload-manifests-by-using-a-multi-stage-pipeline.adocassemblies/mta-ops-guide/assembly_troubleshooting-the-mta-ops-pipeline.adocassemblies/mta-ops-guide/assembly_validating-target-cluster-compatibility.adocassemblies/mta-ops-guide/topicsdocs/mta-ops-guide/assembliesdocs/mta-ops-guide/master-docinfo.xmldocs/mta-ops-guide/master.adocdocs/mta-ops-guide/topicsdocs/topics/mta-ops/con_cluster-context-management.adocdocs/topics/mta-ops/con_introduction-to-the-mta-ops-cli.adocdocs/topics/mta-ops/con_local-manifest-generation.adocdocs/topics/mta-ops/con_manifest-compatibility-validation.adocdocs/topics/mta-ops/con_mta-ops-cli-standalone-architecture.adocdocs/topics/mta-ops/con_mta-ops-pipeline-troubleshooting.adocdocs/topics/mta-ops/con_multi-stage-transformation-pipeline.adocdocs/topics/mta-ops/con_resource-and-api-compatibility.adocdocs/topics/mta-ops/con_stateless-migration-limitations.adocdocs/topics/mta-ops/con_transformation-plugin-management.adocdocs/topics/mta-ops/con_workload-deployment.adocdocs/topics/mta-ops/con_workload-manifest-export.adocdocs/topics/mta-ops/proc_adding-a-custom-transformation-stage.adocdocs/topics/mta-ops/proc_configuring-source-and-target-cluster-contexts.adocdocs/topics/mta-ops/proc_deploying-workloads-to-the-target-cluster-as-a-non-administrator.adocdocs/topics/mta-ops/proc_deploying-workloads-to-the-target-cluster-as-an-administrator.adocdocs/topics/mta-ops/proc_downloading-and-extracting-the-mta-ops-cli.adocdocs/topics/mta-ops/proc_enabling-verbose-logging-for-mta-ops.adocdocs/topics/mta-ops/proc_executing-a-multi-stage-workload-transformation.adocdocs/topics/mta-ops/proc_executing-a-stateless-migration-quickstart.adocdocs/topics/mta-ops/proc_exporting-manifests-from-the-source-cluster.adocdocs/topics/mta-ops/proc_generating-final-manifests-locally.adocdocs/topics/mta-ops/proc_generating-ordered-manifests-locally.adocdocs/topics/mta-ops/proc_resolving-transformation-conflicts.adocdocs/topics/mta-ops/proc_resolving-validation-failures.adocdocs/topics/mta-ops/proc_transforming-manifests-with-an-instructions-file.adocdocs/topics/mta-ops/proc_validating-workload-manifests-against-a-live-cluster.adocdocs/topics/mta-ops/ref_common-migration-pipeline-errors.adocdocs/topics/mta-ops/ref_developer-and-architecture-guides.adocdocs/topics/mta-ops/ref_mta-ops-apply-command-options.adocdocs/topics/mta-ops/ref_mta-ops-export-command-options.adocdocs/topics/mta-ops/ref_mta-ops-transform-command-options.adocdocs/topics/mta-ops/ref_mta-ops-validate-command-options.adoc
| @@ -0,0 +1 @@ | |||
| ../../topics/ No newline at end of file | |||
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '== symlink ==\n'
ls -l docs/mta-ops-guide/topics || true
printf '\n== relevant files ==\n'
git ls-files 'docs/mta-ops-guide/*' 'docs/*topics*' | sed -n '1,200p'
printf '\n== include references ==\n'
rg -n 'include::topics/|topics/' docs/mta-ops-guide -g '!**/*.png' -g '!**/*.jpg' -g '!**/*.gif' || true
printf '\n== master.adoc excerpt ==\n'
sed -n '1,220p' docs/mta-ops-guide/master.adocRepository: migtools/mta-documentation
Length of output: 11826
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '== symlink ==\n'
ls -l docs/mta-ops-guide/topics || true
printf '\n== parent tree ==\n'
find docs -maxdepth 2 -type d | sort | sed -n '1,200p'
printf '\n== top-level topics candidates ==\n'
find . -maxdepth 2 -type d -name topics | sort | sed -n '1,200p'
printf '\n== include references ==\n'
rg -n 'include::topics/|topics/' docs/mta-ops-guide -g '!**/*.png' -g '!**/*.jpg' -g '!**/*.gif' || true
printf '\n== master.adoc excerpt ==\n'
sed -n '1,220p' docs/mta-ops-guide/master.adocRepository: migtools/mta-documentation
Length of output: 2245
Point this symlink at docs/topics.
../../topics/ resolves to a non-existent top-level topics directory, so the include::topics/... paths in docs/mta-ops-guide/master.adoc won’t resolve.
Fix
-../../topics/
+../topics/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ../../topics/ | |
| [Symbolic link → ../topics/] |
mpershina
commented
Jul 7, 2026
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
minor corrections per the coderabbit review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
aufi
reviewed
Jul 8, 2026
| | `--export-dir` | `-e` | The directory path containing the exported resources to be processed. | ||
| | `--transform-dir` | `-t` | The directory path to create the isolated transform stages. | ||
| | `--stage` | | A specific custom or built-in stage directory name to run. | ||
| | `--force` | | A flag to overwrite modified custom stage directories. This is mandatory for re-running custom stages. |
There was a problem hiding this comment.
Note, this is subject of replacement with --overwrite, but that depends on migtools/crane#613, so currently the doc content is correct.
mpershina
commented
Jul 8, 2026
mpershina
commented
Jul 8, 2026
mpershina
commented
Jul 8, 2026
mpershina
commented
Jul 8, 2026
mpershina
commented
Jul 8, 2026
mpershina
commented
Jul 8, 2026
Comment on lines
+35
to
+36
| | A required Custom Resource Definition (CRD) is missing. | ||
| | Install the required Operator on the target cluster. |
Collaborator
Author
There was a problem hiding this comment.
Suggested change
| | A required Custom Resource Definition (CRD) is missing. | |
| | Install the required Operator on the target cluster. | |
| | A required Custom Resource Definition (CRD) does not exist on the target cluster. | |
| | Install the required Operator on the target cluster before you deploy the generated manifests. |
Collaborator
Author
Thanks @aufi, I applied the required changes. Could you please double-check? And these look good, approve the PR? |
mpershina
commented
Jul 9, 2026
mpershina
commented
Jul 9, 2026
mpershina
commented
Jul 9, 2026
mpershina
commented
Jul 9, 2026
mpershina
commented
Jul 9, 2026
vashirova
approved these changes
Jul 10, 2026
vashirova
left a comment
vashirova
left a comment
Collaborator
There was a problem hiding this comment.
@mpershina peer review completed. Impressive work! I have some small notes, but nothing major enough to prevent you from merging.
| = Developer and architecture guides | ||
|
|
||
| [role="_abstract"] | ||
| When you want to extend the `mta-ops` command-line interface (CLI) or understand its internal mechanics, review the upstream developer guides. This helps you build custom plugins or contribute to the project. |
Collaborator
There was a problem hiding this comment.
Do users know where to find them?
Collaborator
Author
There was a problem hiding this comment.
I assume so, but I can check with my SMEs for the link :-)
Collaborator
Author
There was a problem hiding this comment.
@istein1, what would be the correct links to the upstream developer guide(s), please?
Co-authored-by: Valentina Ashirova <107574498+vashirova@users.noreply.github.com>
Collaborator
Author
Ack on the fix! Will keep an eye on it, thank you! |
| + | ||
| [subs="+quotes"] | ||
| ---- | ||
| $ *mta-ops apply -t transform -o output --overwrite* |
There was a problem hiding this comment.
Suggested change
| $ *mta-ops apply -t transform -o output --overwrite* | |
| $ *mta-ops apply -t transform -o output --overwrite --ordered* |
Lets keep --ordered by default
There was a problem hiding this comment.
You reported valid issue with OCP-specific resources might have a wrong dependency order without --ordered.
My initial thought was to keep the quickstart as simple as possible (e.g. using default flags values without explicit -t transform -o output) to let user focus on understanding the core concept with export->transform->apply(->validate) commands flow.
However using more bullet-proof commands flags is not a bad way, I have quite neutral opinion about this.
Collaborator
Author
There was a problem hiding this comment.
Sounds good! Users can check what the --ordered flag is for anyway further in the document.
Collaborator
Author
There was a problem hiding this comment.
Skipping based on Sachin's feedback on Slack.
| + | ||
| [subs="+quotes"] | ||
| ---- | ||
| $ *oc apply -f output/output.yaml* |
There was a problem hiding this comment.
Suggested change
| $ *oc apply -f output/output.yaml* | |
| $ *oc apply -f output/resources/ --recursive* |
As the document is for OCP, this would a better choice. output.yaml might have wrong ordering for OCP resources.
There was a problem hiding this comment.
Good point with OCP-specific resources 👍 While this is a quickstart part of the doc, I'd stay with original content and document it in a separate section, just my point of view.
There was a problem hiding this comment.
@mpershina no need for this change here then.
Collaborator
Author
There was a problem hiding this comment.
Ack! Will just resolve the comment then :-)
Collaborator
Author
There was a problem hiding this comment.
Skipping based on Sachin's feedback on Slack.
mpershina
commented
Jul 15, 2026
mpershina
commented
Jul 15, 2026
aufi
reviewed
Jul 17, 2026
| [role="_abstract"] | ||
| When you adapt complex applications, you can manage transformation plugins to control the pipeline. This ensures the tool cleans specific metadata and applies additional transformations, if needed. | ||
|
|
||
| The `mta-ops` command-line interface (CLI) automatically discovers plugins from the `~/.local/share/crane/plugins/` default path. You can view available plugins by using the `list-plugins` subcommand. |
There was a problem hiding this comment.
One final point related to today's discussions, we might mention here something like: User's custom plugins discovered on their filesystem, can be arbitrary applications. mta-ops in this version doesn't apply any additional restrictions or sandboxing during their execution, so, user should trust those plugins.
Collaborator
Author
There was a problem hiding this comment.
@aufi, is my suggestion correct? BTW, is having crane in the path correct? Or should it be changed to mta-ops?
Suggested change
| The `mta-ops` command-line interface (CLI) automatically discovers plugins from the `~/.local/share/crane/plugins/` default path. You can view available plugins by using the `list-plugins` subcommand. | |
| The `mta-ops` command-line interface (CLI) automatically discovers plugins from the `~/.local/share/crane/plugins/` default path. You can view available plugins by using the `list-plugins` subcommand. Custom plugins discovered on your file system can be arbitrary applications. In this version, `mta-ops` does not apply additional restrictions or sandboxing during plugin execution. Therefore, ensure that you trust these plugins. |
nachandr
reviewed
Jul 17, 2026
nachandr
suggested changes
Jul 17, 2026
nachandr
reviewed
Jul 17, 2026
| | `--input-dir` | `-i` | The directory path containing the final rendered manifests to validate. | ||
| | `--context` | | The local kubeconfig context of the target cluster. | ||
| | `--kubeconfig` | | The path to the kubeconfig file for the target cluster. | ||
| | `--api-resources` | | The path to a captured API surface JSON file for offline validation. |
Collaborator
There was a problem hiding this comment.
Suggested change
| | `--api-resources` | | The path to a captured API surface JSON file for offline validation. | |
| | `--api-resources` | a.| The path to a captured API surface JSON file for offline validation. This flag is mutually exclusive with the following live cluster flags: | |
| * `--context` | |
| * `--kubeconfig` | |
| * `--server` | |
| * `--token` | |
| * `--cluster` | |
| * `--user` |
Collaborator
Author
There was a problem hiding this comment.
Modified it a bit.
mpershina
commented
Jul 17, 2026
| | `--api-resources` | | The path to a captured API surface JSON file for offline validation. | ||
| | `--validate-dir` | | The directory path to save validation reports and failure artifacts. | ||
| | `--output` | `-o` | The format of the generated report file. Valid options are `json` or `yaml`. | ||
| | `--overwrite` | | Overwrite of the validation directory if it already exists. |
Collaborator
Author
There was a problem hiding this comment.
Suggested change
| | `--overwrite` | | Overwrite of the validation directory if it already exists. | |
| | `--overwrite` | | Overwrite of the validation directory if it already exists. | |
| | `--server` | `-s` | The address and port of the Kubernetes API server for the target cluster. | |
| | `--token` | | Bearer token for authentication to the target cluster API server. | |
| | `--cluster` | | The name of the `kubeconfig` cluster to use. | |
| | `--user` | | The name of the `kubeconfig` user to use. |
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
5 participants
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.
The first preview: https://mpershina.github.io/Previews/MTA/mta-ops-new.html
Summary by CodeRabbit
Summary by CodeRabbit
New Features
mta-ops, covering installation, stateless migration quick start, export → transform → local manifest generation/apply, optional validation, deployment, and troubleshooting.Documentation
mta-opscommand options (export/transform/apply/validate).