docs(code-samples): fix invalid CLI flags and YAML in samples

[ekline]

Context

This PR fixes factual inaccuracies in documentation code samples, verified against the current Okteto CLI source (okteto/cmd/) and the canonical Okteto Manifest JSON Schema (okteto/schema.json). Cosmetic and stylistic changes are intentionally out of scope.

Scan summary

• Files scanned: 154 (all doc pages under docs/src/content and docs/src/tutorials)
• Files with High/Medium code-sample findings: 4
• Files fixed this run: 4
• Files deferred: 0

Fixes

File	Location	Issue	Fix
docs/src/content/reference/manifest-migration.mdx	Intro bullet list	Documented okteto deploy --build, a flag that does not exist — the deploy command only defines --no-build (okteto/cmd/deploy/deploy.go:321)	Replaced with accurate behavior: okteto deploy builds pending images by default; --no-build skips the rebuild
docs/src/content/self-hosted/install/auth/okta.mdx	OpenID mapping: YAML example	mapping: indented 5 spaces vs sibling keys at 4 — invalid YAML that fails to parse	De-indented mapping: to 4 spaces to align with enabled/clientId/endpoints
docs/src/content/reference/ssh-server.mdx	Connect using SSH	ssh -P PORT localhost — OpenSSH uses lowercase -p for port; -P is invalid for ssh so the command errors	Changed to ssh -p PORT localhost
docs/src/content/self-hosted/manage/crds.mdx	gcp-cloud-credential.yaml example	spec: indented 1 space — invalid YAML; kubectl apply fails. The parallel AWS block has spec: at column 0	De-indented spec: to column 0

Out of scope (not fixed)

• docs/src/tutorials/optimize-your-development-environment.mdx has a malformed Markdown link missing its closing ). This is a prose link, not a code sample, so it is outside this review's scope — flagged for a separate links/build fix.

Deferred files

None.

---

📝 Created with EkLine · View session

ekline[bot] <202747777+ekline[bot]@users.noreply.github.com>

[netlify]

✅ Deploy Preview for okteto-docs ready!

Name	Link
🔨 Latest commit	a2f3120
🔍 Latest deploy log	https://app.netlify.com/projects/okteto-docs/deploys/6a44b7ea78e6c40008d4f580
😎 Deploy Preview	https://deploy-preview-1282--okteto-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[ekline]

okteto deploy --build does not exist — the deploy command only defines --no-build (confirmed at okteto/cmd/deploy/deploy.go:321). okteto deploy already builds pending images by default, so this line now documents the real --no-build behavior instead.

[ekline]

The OpenSSH client uses lowercase -p for the port; uppercase -P is not a valid ssh option (it is the scp/sftp port flag), so the sample errored as written. Confirmed against OpenSSH ssh(1).

[ekline]

mapping: was indented 5 spaces while its sibling keys (enabled, clientId, endpoints) sit at 4 — invalid YAML that fails to parse. De-indented to 4 spaces so it nests correctly under openid:.

[ekline]

spec: was indented 1 space, making it inconsistent with the top-level keys apiVersion/kind/metadata at column 0 — invalid YAML, so kubectl apply would fail. De-indented to column 0, matching the parallel AWS DynamicConfig block in this same file.

[ifbyol]

@ekline-ai these fixes can be also included in the different documentation versions available within the folder versioned_docs. Could you add the changes on those versions, please?

[ekline]

Done — I backported all four fixes to every version under `versioned_docs/` (1.34 through 1.45). Pushed in a2f3120: 48 files changed (4 files × 12 versions).

Per-version, each snapshot now carries the same corrections as the current-version files:

• `reference/manifest-migration.mdx` — replaced the non-existent `okteto deploy --build` flag with the real `--no-build` behavior
• `reference/ssh-server.mdx` — `ssh -P` → lowercase `-p`
• `self-hosted/install/auth/okta.mdx` — fixed the invalid YAML indentation on `mapping:`
• `self-hosted/manage/crds.mdx` — fixed the invalid YAML indentation on `spec:`

I verified all four buggy patterns are now absent across versioned_docs/ (0 occurrences) and that --no-build — already used correctly in advanced-commands-and-concepts.mdx — is present in all 12 snapshots.

[ekline]

Done. Reply posted to the reviewer.

Backport complete

The reviewer's request — apply the same fixes across the versioned docs — is done and pushed to the open PR.

Commit a2f3120a on PR #1282: 48 files changed (4 files × 12 versions, 1.34 → 1.45).

File (per version)	Fix backported
reference/manifest-migration.mdx	Non-existent okteto deploy --build → real --no-build behavior
reference/ssh-server.mdx	ssh -P → lowercase -p
self-hosted/install/auth/okta.mdx	Invalid YAML indentation on mapping:
self-hosted/manage/crds.mdx	Invalid YAML indentation on spec:

How I verified:

• Located the exact buggy line in each of the 12 snapshots before editing (all 48 present).
• Applied exact-match replacements with a per-file count guard (48/48 edited, 0 skipped/over-matched).
• Re-scanned versioned_docs/: all four buggy patterns now return 0 occurrences; --no-build is present in all 12 (and independently confirmed as a real flag — it's already used correctly in advanced-commands-and-concepts.mdx).

Process: routed through the PR skill in update mode — pre-commit style review ran (0 changes; edits are inside code blocks or an already-reviewed bullet), committed with DCO sign-off, pushed to update the existing PR. No new PR, no title/body or reviewer changes. A confirmation reply is posted on the reviewer's comment.

One note carried over from before: the Slack summary to #C0APP7FMXKM still can't be delivered — the bot isn't a member of that channel and lacks the channels:join scope. Invite the bot (or grant the scope) and I'll post it.