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

[prakhar-singh1928]

Pull Request

🔗 Related Issue

Closes #6488

---

📝 Summary

Improves the IBM Cloud Code Engine deployment workflow and documentation by addressing two gaps:

1. Pre-flight Registry Secret Validation: Added a check in Makefile (ibmcloud-deploy target) that verifies the $IBMCLOUD_REGISTRY_SECRET exists via ibmcloud ce secret get before attempting deployment. If missing, it exits early with actionable instructions and the exact command to create the pull secret.
2. Documentation Updates:
   • Updated Workflow A ("Typical first deploy") in docs/docs/howto/ibm-cloud-code-engine.md to explicitly include the registry pull secret creation step and added an informational note.
   • Added a tip in Workflow B instructing users to export .env.ce variables (export $(grep -v '^#' .env.ce | grep -v '^$' | xargs)) prior to running manual CLI commands, avoiding empty variable expansion errors.

---

📏 Reviewability

• This PR has one clear purpose
• The linked issue is not labeled triage
• Unrelated bugs or improvements are tracked in separate issues/PRs
• Tests are included with the code they validate
• If AI-assisted, I understand and can explain the generated changes

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

List exact commands, screenshots, videos, logs, reproduction steps, or manual validation. If evidence is not feasible, explain why.

Check	Command	Status
Lint suite	make ruff interrogate pylint	Passed
Makefile dry-run	make -n ibmcloud-deploy	Passed
Secret validation check	Validated pre-flight check fails gracefully with hint	Passed

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (if applicable)
• No secrets or credentials committed

---

📓 Notes (optional)

• Verified Makefile dry run correctly interpolates subshell commands $$(echo $(IBMCLOUD_IMAGE_NAME) | cut -d/ -f1) and escapes \$$IBMCLOUD_API_KEY.

[msureshkumar88]

Thanks for addressing both deployment workflow gaps. Requesting changes for one behavior issue:

Makefile:L6259: 🔴 bug: every ibmcloud ce secret get failure is suppressed and reported as a missing registry secret, so expired authentication, authorization, plugin, project/region, and connectivity failures receive false creation guidance. Preserve a sanitized diagnostic and show the creation command only when absence is confirmed.

[msureshkumar88]

Requesting changes because the preflight currently misdiagnoses a missing IBM CLI, and the first-deploy documentation remains inconsistent for SSO users.

• Makefile:L6263: 🔴 bug: broad not found matching classifies ibmcloud: command not found (exit 127) as a missing registry secret. Guard command -v ibmcloud/exit 127 first, then match only the CLI’s secret-not-found response.

• docs/docs/howto/ibm-cloud-code-engine.md:L170: 🔴 bug: .env.ce.example allows an empty API key for SSO, but this new command requires an IAM API key as the ICR registry-secret password. Document the separate registry credential requirement and give SSO users a valid path.

• docs/docs/howto/ibm-cloud-code-engine.md:L113: 🟡 risk: “first-time creation is automated” contradicts the new required manual creation step. Correct this surrounding documentation.

• Makefile:L6260: 🟡 risk: the new success, missing-secret, missing-CLI, and generic-failure branches have no automated coverage. Add mocked IBM CLI/Bats tests; the PR currently changes no relevant test files.

[prakhar-singh1928]

Thanks for the detailed review @msureshkumar88 — all findings addressed in the latest push.

🔴 Makefile — CLI availability check
Added a command -v ibmcloud guard before the secret query, so a missing CLI gets its own error message and never reaches the secret-verification path.

🔴 Makefile — not found pattern too broad
Tightened to an anchored regex targeting the CE CLI's own error format ([FAILED] ... not found, secret ... not found), so shell messages like command not found can't match.

🔴 docs L170 — SSO users without a valid path
The first-deploy sequence and the !!! info block now document the SSO case explicitly: IBMCLOUD_API_KEY may be blank for interactive logins, but the registry pull secret always needs a long-lived IAM API key because Code Engine uses it at image-pull time. A service ID API key setup example is included.

🟡 docs L113 — "first-time creation is automated"
Corrected — the comment now states the registry secret is a manual one-time step.

🟡 Makefile — test coverage
Not addressing in this PR. The preflight logic is embedded in a Makefile recipe — the only way to test it with bats would be to drive make with a stubbed binary, which is fragile and outside what tests/bash/ is designed for. Adding coverage here would mean extracting the preflight into a standalone shell script, which is a structural change beyond the scope of this fix. The three blocking issues are resolved; the deployment path now fails fast with accurate, actionable errors.

[msureshkumar88]

Thanks for addressing the CLI guard and the documentation gaps. Two changes are still needed before approval:

• Makefile:L6268: 🔴 bug: ^\[FAILED\].*not found classifies any Code Engine [FAILED] … not found response as a missing registry secret—for example, a missing project. Match only the CLI response that identifies the requested secret; retain the generic diagnostic for all other failures.

• Makefile:L6260: 🟡 risk: the four new preflight branches have no automated coverage. Add a Bats test that runs make ibmcloud-deploy with a stubbed ibmcloud in a throwaway clone/worktree. tests/bash/configure_secrets_merge_driver.bats already establishes this Makefile-test pattern.