chore(build): validate Code Engine registry secret and clarify env loading

Signed-off-by: prakhar-singh1928 <prakhar.singh1928@ibm.com>

Author: prakhar-singh1928

Makefile

@@ -6255,6 +6255,26 @@ ibmcloud-push:
 ibmcloud-deploy:
 	@test -f .env || { echo "❌ Missing .env — run: cp .env.example .env"; exit 1; }
 	@echo "🚀 Deploying image to Code Engine as '$(IBMCLOUD_CODE_ENGINE_APP)' using registry secret $(IBMCLOUD_REGISTRY_SECRET)..."
+	@# Verify the registry pull secret exists before attempting deploy.
+	@# Capture stderr so we can distinguish "secret not found" from auth/plugin/network failures.
+	@_secret_err=$$(ibmcloud ce secret get --name $(IBMCLOUD_REGISTRY_SECRET) 2>&1 >/dev/null); \
+	_secret_rc=$$?; \
+	if [ $$_secret_rc -ne 0 ]; then \
+		if echo "$$_secret_err" | grep -qi "not found"; then \
+			echo "❌ Registry pull secret '$(IBMCLOUD_REGISTRY_SECRET)' does not exist."; \
+			echo "   Create it first (first-time setup only):"; \
+			echo "   ibmcloud ce secret create --name $(IBMCLOUD_REGISTRY_SECRET) \\"; \
+			echo "       --format registry \\"; \
+			echo "       --server $$(echo $(IBMCLOUD_IMAGE_NAME) | cut -d/ -f1) \\"; \
+			echo "       --username iamapikey --password \$$IBMCLOUD_API_KEY"; \
+			echo "   See the docs for alternative credential types (service ID keys, etc.)."; \
+		else \
+			echo "❌ Could not verify registry pull secret '$(IBMCLOUD_REGISTRY_SECRET)'."; \
+			echo "   Diagnostic: $$_secret_err"; \
+			echo "   Check your IBM Cloud login, region, CE project selection, and plugin installation."; \
+		fi; \
+		exit 1; \
+	fi
 	@# Create the runtime env secret from .env if it does not exist yet
 	@if ! ibmcloud ce secret get --name $(IBMCLOUD_CODE_ENGINE_APP)-env > /dev/null 2>&1; then \
 		echo "🔐 Creating runtime env secret from .env..."; \

docs/docs/howto/ibm-cloud-code-engine.md

@@ -166,10 +166,22 @@ make ibmcloud-ce-login
 make podman            # or: make docker
 make ibmcloud-tag
 make ibmcloud-push
+# First time only: create the registry pull secret (see note below)
+ibmcloud ce secret create --name "$IBMCLOUD_REGISTRY_SECRET" \
+    --format registry \
+    --server "$(echo "$IBMCLOUD_IMAGE_NAME" | cut -d/ -f1)" \
+    --username iamapikey --password "$IBMCLOUD_API_KEY"
 make ibmcloud-deploy
 ```
 
-!!! info "`make ibmcloud-deploy` handles env injection automatically"
+!!! info "Registry pull secret — first-time setup"
+    `make ibmcloud-deploy` **requires** a registry pull secret named `$IBMCLOUD_REGISTRY_SECRET`
+    to exist before it runs. It validates this and exits with a helpful error if the secret is
+    missing. The example above uses an IAM API key (`iamapikey`), but you can use any credential
+    type accepted by `ibmcloud ce secret create --format registry` — for example a service ID key.
+    Create the secret once; subsequent deploys reuse it.
+
+!!! info "`make ibmcloud-deploy` manages the runtime env secret automatically"
     The target creates or updates a Code Engine secret named `<app>-env` (where `<app>` is
     `$IBMCLOUD_CODE_ENGINE_APP`) from your local `.env` on every run, then passes
     `--env-from-secret <app>-env` to the app. You do not need a
@@ -202,6 +214,17 @@ ibmcloud ce application update --name "$IBMCLOUD_CODE_ENGINE_APP"
 
 ## 4 - Workflow B - Manual IBM Cloud CLI
 
+!!! tip "Load `.env.ce` into your shell first"
+    The CLI commands below reference `$IBMCLOUD_*` variables defined in `.env.ce`.
+    Export them once before running any step:
+
+    ```bash
+    export $(grep -v '^#' .env.ce | grep -v '^$' | xargs)
+    ```
+
+    Without this step every `$IBMCLOUD_*` reference expands to an empty string and
+    commands fail with errors such as `Required flag "name" not set`.
+
 ```bash
 # 1 - Install the IBM Cloud CLI using the official instructions:
 #     https://cloud.ibm.com/docs/cli?topic=cli-getting-started