Skip to content

docs: add migration guide from Ona (formerly Gitpod) to Coder - #31204

Merged
nickvigilante merged 1 commit into
mainfrom
docs/migrate-from-ona
Nov 5, 2026
Merged

nickvigilante merged 1 commit into
mainfrom
docs/migrate-from-ona

Conversation

@coder

@coder coder Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Note

Generated by Coder Agents on behalf of @nickvigilante.

Adds a migration guide for platform engineers moving an Ona (formerly Gitpod) Enterprise deployment to a self-hosted Coder deployment. Tracks DOCS-1415.

@david-fraley @nickvigilante, this is a first draft for review.

What the guide assumes

It's written for a typical enterprise Ona setup: Ona-hosted management plane, AWS or GCP runners in the customer's VPC, OIDC SSO with SCIM, groups and org roles, projects with devcontainer.json and .ona/config.yaml, org/project/user secrets, daily prebuilds with a service-account executor, org policies (auto-stop, max lifetime, archive/auto-delete, port sharing, security agents, deny lists), Codex Agent with Ona Intelligence or BYOK, MCP integrations, and Automations triggered by PRs, schedules, and webhooks.

How it converts

  • Management plane: self-hosted control plane and PostgreSQL, OIDC, SCIM, IdP sync, orgs, and service accounts
  • Runners and environment classes: templates, provisioners, and instance-type parameters
  • Projects: workspace presets on a shared template, with template permissions
  • devcontainer.json: Dev Containers integration (VM templates) or Envbuilder (Kubernetes)
  • .ona/config.yaml triggers: dev container lifecycle commands, coder_script, and coder_app
  • Prebuilds and warm pools: Envbuilder caching and prebuilt workspaces
  • Secrets, policies, editors, dotfiles, and auditing: their Coder equivalents
  • Codex Agent and Automations: Coder Agents (or Codex CLI behind AI Gateway), plus the Chats API called from CI, schedulers, or webhooks

Verification

  • Ona mappings were checked against Ona's current docs (ona.com/docs) on 2026-10-23.
  • Coder claims were checked against main at 78aa570.
  • Registry template and module paths were confirmed in coder/registry.
  • make docs/manifest.json, pnpm run format-docs, pnpm run check-docs, and Vale all pass.

Open questions for review

Rebase onto main (conflict resolution)
  • Rebased onto main at 585485c. docs/manifest/tutorials.yml and docs/tutorials/ no longer exist, so the page moved to Install > Plan your deployment, after Sizing.
  • Rewrote every relative link that pointed at a moved page, using the rules in docs/redirects.json (admin/templates to templates, ai-coder/* to coder-agents and ai-governance, user-guides to workspaces, and the old Tutorials pages to their new sections). The prose is unchanged.
  • Regenerated docs/manifest.json with make gen/docs-manifest.
  • Checks: pnpm run check-docs, make lint/docs-manifest, make lint/docs-redirects, and the pre-commit hook pass, and every link and anchor resolves.
  • Not addressed: docs: promote usage of Nix(OS) and discourage use of envbuilder #31141 put Envbuilder in maintenance mode after this guide was written, but the guide still recommends Envbuilder for Kubernetes and Envbuilder caching for prebuilds. Vale also reports new AbbreviationFirstUse and StepLength warnings, which are advisory only.

@github-actions github-actions Bot added the community Pull Requests and issues created by the community. label Oct 23, 2026
@coder
coder Bot requested review from david-fraley and nickvigilante October 23, 2026 17:02
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@david-fraley
david-fraley removed their request for review November 4, 2026 15:42
@david-fraley

Copy link
Copy Markdown
Collaborator

Spoke with @nickvigilante; removing myself as a reviewer. Nick will handle any follow ups.

@nickvigilante
nickvigilante requested a review from bpmct November 4, 2026 17:35
@nickvigilante
nickvigilante marked this pull request as ready for review November 4, 2026 20:07

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nickvigilante
nickvigilante merged commit f55e12e into main Nov 5, 2026
33 of 34 checks passed
@nickvigilante
nickvigilante deleted the docs/migrate-from-ona branch November 5, 2026 18:26
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants