From 7cf0c98adc38961f743ab56a09300d811382237b Mon Sep 17 00:00:00 2001
From: Siu Wa Wu <siwu@redhat.com>
Date: Tue, 18 Aug 2026 15:57:26 +1000
Subject: [PATCH 1/3] Update docs about managed-scripts testing method

---
 README.md                       |  8 +++----
 docs/testing-managed-scripts.md | 39 +++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 docs/testing-managed-scripts.md

diff --git a/README.md b/README.md
index cbd7afe3..dd08933e 100644
--- a/README.md
+++ b/README.md
@@ -90,10 +90,10 @@ To setup the PS1(prompt) for bash/zsh, please follow [these instructions](https:
 | `ocm backplane managedJob list [flags]`                                     | Retrieve a list of backplane managed job resources                                       |
 | `ocm backplane managedJob logs <job_name> [flags]`                          | Retrieve logs of the specified managed job resource                                      |
 | `ocm backplane managedJob delete <job_name> [flags]`                        | Delete the specified managed job resource                                                |
-| `ocm backplane testJob create <script> [flags]`                             | Create a backplane test managed job on a non-production cluster for testing. To use with bash libraries, make sure the libraries are in the scripts directory in the format `source /managed-scripts/<path-from-managed-scripts-scripts-dir>`                      |
-| `ocm backplane testJob get <job_name> [flags]`                              | Retrieve a backplane test job resource                                                   |
-| `ocm backplane testJob list [flags]`                                        | Retrieve a list of backplane test job resources                                          |
-| `ocm backplane testJob logs <job_name> [flags]`                             | Retrieve logs of the specified test job resource                                         |
+| `ocm backplane testJob render [flags]`                                      | Render the Kubernetes YAML (ServiceAccount, RBAC and Pod) for a draft managed script locally, so it can be applied directly with `oc apply -f`. See [Testing a draft managed script](docs/testing-managed-scripts.md). |
+| `ocm backplane testJob create <script> [flags]`                             | (Deprecated, use `testJob render` instead) Create a backplane test managed job on a non-production cluster for testing.                   |
+| `ocm backplane testJob get <job_name> [flags]`                              | (Deprecated, use `testJob render` instead) Retrieve a backplane test job resource                                                        |
+| `ocm backplane testJob logs <job_name> [flags]`                             | (Deprecated, use `testJob render` instead) Retrieve logs of the specified test job resource                                              |
 | `ocm backplane upgrade`                                                     | Upgrade backplane-cli to the latest version                                              |
 | `ocm backplane version`                                                     | Display the installed backplane-cli version                                              |
 | `ocm backplane healthcheck`                                                 | Check the VPN and Proxy connectivity on the host network when experiencing isssues accessing the backplane API|
diff --git a/docs/testing-managed-scripts.md b/docs/testing-managed-scripts.md
new file mode 100644
index 00000000..15367380
--- /dev/null
+++ b/docs/testing-managed-scripts.md
@@ -0,0 +1,39 @@
+# Testing a draft managed script
+
+When developing a new [managed script](https://github.com/openshift/managed-scripts), you often want to run your draft before it is merged.
+
+Previously this was done with `ocm backplane testJob create/get/logs`, which required the backplane API to build and run a test job. Those subcommands are now **deprecated**.
+
+The recommended way is `ocm backplane testJob render`, which generates the Kubernetes YAML (ServiceAccount, RBAC and Pod) for your script **locally** — no backplane API call is made. You then apply it directly on a non-production cluster where you have cluster-admin access.
+
+## Example
+
+Assuming your draft script lives in a directory that contains a `metadata.yaml` and the script itself (the same layout used in the [managed-scripts](https://github.com/openshift/managed-scripts) repo):
+
+```bash
+# 1. Log in to a non-production cluster with cluster-admin access
+oc login <cluster-api-url>
+
+# 2. Render the YAML from your script directory
+cd scripts/SREP/example
+ocm backplane testJob render -p VAR1=val1 > test-job.yaml
+
+# 3. Review the generated YAML, then apply it
+oc apply -f test-job.yaml
+
+# 4. Watch the job and inspect its logs with standard oc commands
+oc -n openshift-backplane-managed-scripts get pods
+oc -n openshift-backplane-managed-scripts logs <pod-name>
+
+# 5. Clean up after testing
+oc delete -f test-job.yaml
+```
+
+## Useful flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `-p, --params 'VAR1=val1'`        | Pass parameters to the script (repeatable, e.g. `-p 'VAR1=val1' -p VAR2=val2`). |
+| `-s, --source-dir <dir>`          | Directory of the script to render (defaults to the current directory).          |
+| `-i, --base-image-override <img>` | Container image used to run the script. Defaults to the latest managed-scripts image resolved from GitHub. |
+| `-o, --output <file>`             | Write the rendered YAML to a file instead of stdout.                            |

From 5db9eeeda8eedde30f56d0d089c3c72da4a29949 Mon Sep 17 00:00:00 2001
From: Siu Wa Wu <siwu@redhat.com>
Date: Tue, 18 Aug 2026 17:07:35 +1000
Subject: [PATCH 2/3] address comments

---
 docs/testing-managed-scripts.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/testing-managed-scripts.md b/docs/testing-managed-scripts.md
index 15367380..a0a500ba 100644
--- a/docs/testing-managed-scripts.md
+++ b/docs/testing-managed-scripts.md
@@ -6,6 +6,10 @@ Previously this was done with `ocm backplane testJob create/get/logs`, which req
 
 The recommended way is `ocm backplane testJob render`, which generates the Kubernetes YAML (ServiceAccount, RBAC and Pod) for your script **locally** — no backplane API call is made. You then apply it directly on a non-production cluster where you have cluster-admin access.
 
+
+## Prerequisite
+You have a non-production ROSA cluster that you own or control, with cluster-admin permissions to create resources in it.
+
 ## Example
 
 Assuming your draft script lives in a directory that contains a `metadata.yaml` and the script itself (the same layout used in the [managed-scripts](https://github.com/openshift/managed-scripts) repo):

From 19d72138efeb3957af8ffbfe910d32c054fbde03 Mon Sep 17 00:00:00 2001
From: Siu Wa Wu <siwu@redhat.com>
Date: Wed, 19 Aug 2026 10:52:53 +1000
Subject: [PATCH 3/3] make it clear for testjob render prerequisite

---
 docs/testing-managed-scripts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/testing-managed-scripts.md b/docs/testing-managed-scripts.md
index a0a500ba..c8ef9ce5 100644
--- a/docs/testing-managed-scripts.md
+++ b/docs/testing-managed-scripts.md
@@ -8,7 +8,7 @@ The recommended way is `ocm backplane testJob render`, which generates the Kuber
 
 
 ## Prerequisite
-You have a non-production ROSA cluster that you own or control, with cluster-admin permissions to create resources in it.
+You have a non-production ROSA cluster that you own or control, with cluster-admin permissions to create resources in it. For example, your own cluster with direct cluster-admin access via IDP, or a staging cluster where you have backplane elevation permissions.
 
 ## Example