docs(tutorial): getting started with Agentic Workflows

[ekline]

Context

Tutorial and how-to gap review across eight competitors (Coder, Ona/ex-Gitpod, Qovery, Orca, Paseo, herdr, Signadot, Telepresence), persona needs, and a coverage audit of src/content/ and src/tutorials/.

Top 3 gaps

Rank	Priority	Gap	Source	Personas served	Proposed guide type
1	High	No followable, end-to-end guide for running an AI coding agent against a live Okteto environment. The four src/content/agentic/ pages are explanation/reference; plugin install is the only executable procedure, and both "Workflow example" sections are narrated with placeholder hosts and no prerequisites, numbered steps, or verification.	All 8 competitors teach this; Coder, Ona, Signadot and Qovery each dedicate a whole section to it. Okteto gave it a top-level sidebar category and a 1.47 in-product entry point.	Developer, new user	Tutorial
2	High	No page for attaching an IDE to a Development Container. IDE setup exists only as "Step 4: Remote debugging" inside the 7 per-language file-sync tutorials; JetBrains coverage is language-fragmented and Cursor has none.	Coder and Ona both publish near-identical per-editor matrices (VS Code, JetBrains, Cursor, Windsurf, Zed).	Developer	How-to
3	Medium	No guide for migrating an existing local Docker Compose or local dev setup to Okteto. compose-getting-started deploys a sample repo that already ships a working compose file. The okteto-onboarding skill implements exactly this migration and has no human-facing counterpart.	Telepresence ships "Extend Docker Compose with Telepresence"; Qovery covers repo onboarding via blueprints. Category-wide gap.	Developer, new user	How-to

What this PR adds

src/tutorials/agentic-workflows.mdx — "Getting started with Agentic Workflows", the first followable end-to-end tutorial for the Agentic Workflows section. Built on the okteto/movies sample app, which already ships a CLAUDE.md and a /dev-setup command.

Five steps, each with a verification point:

1. Installing the Okteto plugin — verified by asking the agent to read okteto.yaml
2. Deploying the environment with your agent — okteto deploy --wait plus okteto endpoints
3. Fixing a regression alongside your agent (collaborative) — reader plants .limit(5) in catalog/server.js; the agent finds it via okteto test e2e, fixes it, and File Sync delivers the fix with no redeploy
4. Handing the agent a task end to end (autonomous) — the agent adds a count endpoint on the catalog service, then runs the deploy-test loop
5. Making verification the default — repository instructions so the agent deploys even when the prompt never mentions Okteto

Placement follows the precedent set by Divert and Preview Environments: hands-on sample-app tutorial in src/tutorials/, explanation and how-to in src/content/.

Personas served: developers adopting agent workflows, and new users evaluating Okteto for agent work.

Research sources

• Competitors covering this topic: all eight. Coder ("Run AI Coding Agents in Coder": Tasks, MCP Server, AI Gateway, Agent Firewall), Ona (repositioned entirely around background agents), Signadot (its four newest tutorials are agent-driven closed-loop validation with Cursor, Claude Code and Codex), Qovery ("Deploy with an AI agent" quickstart plus the RDE agent portal), and Orca, Paseo and herdr — three products whose entire docs sets are about running agents in isolated workspaces.
• Coverage audit: every user-facing feature shipped in 1.44–1.47 landed reference-only. The Agentic Workflows section had zero tutorials and one how-to procedure (plugin install), despite being the newest top-level section with in-product discovery pointing at it since 1.47.

Remaining gaps (follow-up work)

• Sample for working with npm link #2 — IDE-to-Development-Container guide. Consolidate the per-language remote-debugging steps into one page and add Cursor.
• document how to use a custom pipeline image #3 — Migrating from local Docker Compose or local dev to Okteto. Human-facing counterpart to the okteto-onboarding skill.

Also surfaced during the audit, worth separate issues:

• Three items undocumented at any level: OKTETO_IS_REDEPLOY (okteto#5076), the persistent column in okteto namespace list / okteto preview list (okteto#4900), and Gateway API HTTPRoute Compose endpoints (okteto#4898, #4934, #4991).
• x-okteto-identity-token (1.46) has reference syntax but no how-to, though the task spans Okteto config and cloud-side IAM trust-policy setup.
• Duplicate ## Step 3 headings in src/content/testing/getting-started-test.mdx.
• src/content/development/deploy/develop-on-okteto-button.mdx description is copy-pasted from its sibling page.

How to verify

yarn build was NOT run — Node and yarn are unavailable in this environment. Please run it before merging; it validates links and anchors.

Facts verified by reading source rather than execution:

• Services, technologies and the e2e Test Container against movies/okteto.yaml
• The .limit(5) edit against the real catalog/server.js:25; find() returns a FindCursor in mongodb v6, so .limit(5).toArray() is valid
• Six movies in the catalog against catalog/data/catalog.json and the main.spec.js:23 assertion
• e2e test names and line numbers (main.spec.js:3:1, :11:1, :18:1)
• catalog/server.js syncs during okteto up — catalog/.stignore has no matching entry
• yarn start runs nodemon (catalog/package.json:14), so the collaborative fix reaches the container without a redeploy
• okteto test does not redeploy unless --deploy is passed (okteto/cmd/test/cmd.go:133), so the dev container survives the test run
• The new endpoint needs no chart change — the catalog ingress routes the catalog path prefix
• okteto endpoints prints one URL per ingress path (okteto/pkg/k8s/ingresses/crud.go:149-150); all five paths listed
• okteto down restores the previous deployment rather than destroying it (okteto/cmd/down.go:51-52)

To walk the tutorial end to end you need an Okteto instance, the Okteto CLI configured, and Claude Code with the plugin installed.

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

---

📝 Created with EkLine · View session

[netlify]

✅ Deploy Preview for okteto-docs ready!

Name	Link
🔨 Latest commit	f86f272
🔍 Latest deploy log	https://app.netlify.com/projects/okteto-docs/deploys/6a7c4a1ed6e3430008de8458
😎 Deploy Preview	https://deploy-preview-1327--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.