Skip to content
Coder Docs

Migrate from Ona (formerly Gitpod) to Coder

Move an Ona Enterprise deployment, including runners, projects, policies, and agents, to a self-hosted Coder deployment.

On this page

This guide is for platform engineers who run an Ona Enterprise organization with runners in AWS or Google Cloud and want to move it to a self-hosted Coder deployment. It maps each part of an Ona deployment to its Coder equivalent, then walks through the migration in the order most teams do it.

Ona was previously named Gitpod, and some Ona paths, such as the /home/gitpod home directory, still use the old name. This guide uses "Ona" throughout.

Before you begin

You need:

  • Organization admin access to Ona, so you can read runner, project, policy, and integration settings.
  • A Coder Premium license if you plan to use the features marked Premium in this guide. Most organization-wide policy, identity, and governance features that Ona Enterprise includes require Premium.
  • A Kubernetes cluster or VM and a PostgreSQL database in the cloud account where you want the Coder control plane to run.
  • Permission to create an OAuth application on each Git host your developers use.

How the two architectures differ

Ona splits its platform into 2 planes. Ona hosts the management plane, which handles authentication, organization settings, guardrails, and coordination. Runners in your AWS or Google Cloud account provision environments, clone code, inject secrets, and run agents.

Coder has no vendor-hosted component. You run the control plane and its PostgreSQL database, and Coder provisions workspaces from templates that you write in Terraform. The Coder Agents agent loop also runs in your control plane.

In practice, migrating means 2 things:

  • Identity, organization settings, policies, audit data, and agent configuration move from Ona's management plane into a deployment you operate.
  • Runner configuration, environment classes, and projects become Terraform templates.

Concept mapping

Use this table to find where each Ona concept lives in Coder. The sections that follow cover each area in detail.

OnaCoder
Management planeCoder control plane and PostgreSQL, which you host
Runner (AWS or GCP)The infrastructure a template provisions, plus provisioners that run Terraform
Environment classA template parameter for instance size
ProjectA template, with one workspace preset per repository
EnvironmentWorkspace
devcontainer.jsonDev Containers integration or Envbuilder
Tasks and services in .ona/config.yamlDev container lifecycle commands, coder_script, and coder_app
Prebuilds and warm poolsEnvbuilder caching and prebuilt workspaces
Organization and project secretsValues that templates inject from your secret manager (refer to Secrets)
User secretsUser secrets
Git providers configured on each runnerExternal authentication, configured once for the deployment
Codex AgentCoder Agents, or Codex CLI running in a workspace
AutomationsThe Chats API, called from CI, schedulers, or webhooks
Custom domainAccess URL and wildcard access URL
Ona Terraform providercoderd Terraform provider

Inventory your Ona organization

Record the current configuration before you change anything. You use this inventory to build templates and to confirm that nothing was left behind.

Collect the following from the Ona dashboard, the Ona CLI, or your Ona Terraform configuration:

  • Runners: cloud, account, region, VPC, network mode (such as AWS PrivateLink or an internal load balancer), proxy, and custom certificate authority (CA) settings.
  • Environment classes: the instance type, disk size, and GPU settings for each runner.
  • Projects: repository, default branch, Dev Container path, tasks and services path, allowed environment classes, recommended editors, and who the project is shared with.
  • Secrets: the name, scope (organization, project, or user), and type (environment variable, file, or container registry) of each secret. Collect secret values from their source of truth, such as your secret manager, instead of from Ona.
  • Policies: every setting under Settings > Organization > Policies.
  • Identity: SSO providers, verified domains, System for Cross-domain Identity Management (SCIM) configuration, groups, teams, organization roles, and service accounts.
  • Git providers: each Git host configured on each runner, and whether it uses OAuth, personal access tokens, or both.
  • Agents: model access configuration, LLM integrations, Model Context Protocol (MCP) integrations, and any AGENTS.md files and skills in your repositories.
  • Automations: each Automation's trigger, steps, target repositories, and the identity it runs as. If you manage Automations as code, the YAML files in your repositories already capture this.

Deploy the Coder control plane

Deploy Coder in the same cloud account and network as your Ona runners. Workspaces then reach the same internal services, package registries, and databases that your Ona environments use today.

  1. Size the deployment with the Coder validated architectures.
  2. Install the control plane on Kubernetes or on a cloud VM.
  3. Connect an external PostgreSQL database, such as Amazon RDS or Cloud SQL.
  4. Set the access URL and wildcard access URL to replace the Ona custom domain.
  5. If developers depend on the deployment for daily work, run multiple replicas for high availability.

If your Ona runners span several regions, deploy workspace proxies (Premium) near each group of developers. If your network has no outbound internet access, follow the air-gapped deployment guide.

Connect your identity provider

Connect the same identity provider that Ona uses so that developers sign in with their existing accounts.

OnaCoder
SSO through an OIDC providerOpenID Connect
SCIM provisioningSCIM (Premium)
Groups and teamsGroups (Premium), synced from your identity provider with IdP sync (Premium)
Organization rolesRoles and custom roles (Premium)
Multiple Ona organizationsOrganizations (Premium)
Service accountsService accounts (Premium)

Create a Coder service account for each Ona service account that runs Automations or prebuilds. You use their API tokens later, when you move Automations to the Chats API.

Configure Git providers

Ona configures Git providers on each runner, and each developer authorizes their own account. Coder configures Git providers once for the deployment through external authentication, and each developer still authorizes their own account.

  1. Create an OAuth application on each Git host in your inventory.
  2. Add each one to Coder with the CODER_EXTERNAL_AUTH_<n>_* environment variables.
  3. For self-hosted GitHub Enterprise, set API_BASE_URL as described in Git providers for Coder Agents.
  4. Add the external authentication provider to each template so that workspaces can clone and push.

Coder supports GitHub, GitLab, Bitbucket, and Azure DevOps, which covers the Git providers that Ona supports.

Replace runners and environment classes with templates

An Ona runner decides where environments run, and its environment classes decide how large they are. In Coder, the Terraform in each template makes both decisions.

Choose where workspaces run

Ona environments run as EC2 instances on AWS runners and as Compute Engine instances on GCP runners. To keep the same isolation model, start from a VM-based template for the same cloud. The Coder Registry has starting points for AWS, Google Cloud, and Kubernetes.

The control plane runs Terraform with its built-in provisioners by default. If different regions or accounts need separate credentials or network access, run external provisioners in each one and route templates to them with provisioner tags. Give provisioners cloud credentials through the environment they run in, as described in Provider authentication.

Recreate environment classes

Replace each environment class with an option on a template parameter. This example matches the default AWS runner classes:

data "coder_parameter" "instance_type" {
  name         = "instance_type"
  display_name = "Instance type"
  type         = "string"
  default      = "m6i.xlarge"
  mutable      = false

  option {
    name  = "Small (2 vCPU, 8 GiB)"
    value = "m6i.large"
  }
  option {
    name  = "Regular (4 vCPU, 16 GiB)"
    value = "m6i.xlarge"
  }
  option {
    name  = "Large (8 vCPU, 32 GiB)"
    value = "m6i.2xlarge"
  }
}

Pass the value to the instance resource in your template, such as instance_type = data.coder_parameter.instance_type.value.

Recreate projects

An Ona project combines a repository, a Dev Container path, and a set of allowed environment classes. In Coder, you can represent each project as a workspace preset on a shared template:

data "coder_workspace_preset" "payments_api" {
  name = "payments-api"
  parameters = {
    repo_url      = "https://github.example.com/acme/payments-api"
    instance_type = "m6i.xlarge"
  }
}

If a project needs different infrastructure, such as GPUs or a separate network, create a separate template for it. Use template permissions (Premium) to limit who can use each template, as Ona project sharing does.

Keep data across restarts

Ona environments keep their disk across stops and starts. In Coder, what persists depends on the template. Many templates keep the home directory on a persistent volume and recreate compute on each start. Refer to Resource persistence to choose what to keep.

Bring your Dev Container configuration

Ona builds every environment from a devcontainer.json file, so most repositories already have one. Keep it in place and choose how Coder runs it:

  • Dev Containers integration: runs the @devcontainers/cli and Docker inside the workspace. Use it with VM-based templates, where Docker is available. Coder shows each dev container in the dashboard and supports multiple dev containers per workspace.
  • Envbuilder: builds the workspace image itself from devcontainer.json, without a Docker daemon. Use it on Kubernetes, or wherever privileged containers aren't allowed.

This example clones the project repository and starts its dev container with the Dev Containers integration:

module "git-clone" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/git-clone/coder"
  agent_id = coder_agent.dev.id
  url      = data.coder_parameter.repo_url.value
}

module "devcontainers-cli" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/devcontainers-cli/coder"
  agent_id = coder_agent.dev.id
}

resource "coder_devcontainer" "project" {
  count            = data.coder_workspace.me.start_count
  agent_id         = coder_agent.dev.id
  workspace_folder = module.git-clone[0].repo_dir
}

Before you test, check each devcontainer.json and its scripts for these Ona-specific details:

  • Hardcoded paths under /home/gitpod or /workspaces/<repository-name>, which are Ona's default locations. Replace them with paths that match your template, or with variables such as ${containerWorkspaceFolder}.
  • network_mode: host on Docker Compose services, which Ona requires. Keep it only if your services still need it.
  • forwardPorts entries with host:port syntax for Docker Compose sidecar containers, which the Dev Containers integration doesn't support yet. Refer to the Dev Containers limitations.

Translate tasks and services

Ona runs tasks and services from .ona/config.yaml. Coder has no equivalent file, so move each entry to the dev container lifecycle commands or to the template.

Ona triggerWhen Ona runs itCoder equivalent
prebuildDuring prebuilds onlyonCreateCommand or updateContentCommand in devcontainer.json
postDevcontainerStartAfter the dev container first starts or rebuildspostCreateCommand in devcontainer.json
postEnvironmentStartEvery time the environment startspostStartCommand in devcontainer.json, or a coder_script with run_on_start = true
manualOn demand from the UI or CLIA coder_app with a command, or a custom app in devcontainer.json

Ona services are long-running processes, such as databases and development servers. In Coder, start them with a coder_script and expose their ports with a coder_app:

resource "coder_script" "postgres" {
  agent_id     = coder_agent.dev.id
  display_name = "PostgreSQL"
  run_on_start = true
  script       = "docker compose up -d postgres"
}

If the service runs inside a dev container, define it as a custom app with a health check in devcontainer.json instead.

Speed up workspace startup

Ona prebuilds snapshot the Dev Container filesystem on a schedule, and warm pools keep instances running so environments start faster. Coder offers 2 features for the same goal:

  • Envbuilder caching: pushes built image layers to a registry, so later builds of the same devcontainer.json skip unchanged steps.
  • Prebuilt workspaces (Premium): keeps a pool of running workspaces for each preset. When a developer creates a workspace with that preset, Coder assigns them one from the pool, much like an Ona warm pool.

Ona runs prebuilds without user secrets. In Coder, a prebuilt workspace belongs to the prebuilds system user until a developer claims it. Run steps that need the developer's identity, such as cloning with their Git credentials, after the claim.

Refer to Speed up your workspaces for more ways to reduce startup time.

Move secrets

Ona has secrets at 3 scopes. Move each scope as follows:

  • Organization and project secrets: give the workspace compute a cloud identity, such as an Identity and Access Management (IAM) role or service account, and read values from your secret manager at startup. Alternatively, use dynamic secrets that the template creates for each workspace. Do not put secret values in template code or template parameters, because users with template or workspace access can read them.
  • User secrets: ask developers to recreate them as Coder user secrets. Each user secret can target an environment variable, a file path, or both, like Ona environment variable and file secrets.
  • Container registry secrets: give the provisioner or workspace infrastructure access to the registry. For Kubernetes, use an image pull secret. For Envbuilder, follow its security and caching guidance.

If your environments use Ona OIDC tokens to reach AWS or other cloud services, attach a cloud identity to the workspace compute in your template instead.

Recreate organization policies

Recreate each Ona policy in your inventory with the matching Coder setting.

Ona policyCoder setting
Auto-stop timeoutAutostop and activity detection, with defaults set in template scheduling
Maximum environment lifetimeAutostop requirement (Premium)
Archive timing and auto-deleteDormancy threshold and dormancy auto-deletion (Premium)
Environment limitsQuotas (Premium), which limit workspaces by a per-group budget
Project creationTemplate permissions and roles (Premium)
Editor restrictionsThe IDE apps and modules that you include in each template
Port sharingMaximum port sharing level (Premium)
Default imageThe base image or default devcontainer.json in each template
Security agentsThe workspace image or template, where you install the security agent
Command deny list and executable deny listAgent Firewall (Premium) for agent network access, and your workspace image for executables

Set up editors and dotfiles

Ona connects editors to environments over SSH. Coder does the same, so developers keep the editors they use today:

Developers can keep their Ona dotfiles repository. Ona and Coder both clone the repository and run the first install script they find, such as install.sh, bootstrap.sh, or setup.sh. Add the dotfiles module to your templates, then refer developers to Dotfiles.

If your repositories have a "Build with Ona" README button, replace it with an Open in Coder link.

Move agent workloads

Ona runs the Codex harness as its agent, with OpenAI model access through Ona Intelligence or an approved provider integration. In Coder, choose one of 2 approaches, or use both:

  • Coder Agents: the agent loop runs in the control plane, so workspaces need no agent software or LLM credentials. It works with Anthropic, OpenAI, Google, Azure, AWS Bedrock, and any OpenAI-compatible endpoint.
  • Codex CLI in a workspace: install it with the Codex module, and route its traffic through AI Gateway (Premium) for centralized keys and auditing.

Configure Coder Agents

  1. Add your LLM providers and models, as described in Getting started. If your Ona runners used Bedrock or a direct OpenAI integration, you can reuse that account.
  2. Write clear template descriptions, because Coder Agents uses them to choose a template for each task.
  3. Set a deployment system prompt and organization instructions in Platform controls.
  4. Register the MCP servers from your Ona organization integrations as MCP servers.
  5. Keep the AGENTS.md files in your repositories.
  6. Move skills to a location that Coder Agents scans, as listed in Extending agents.

Community and Premium licenses allow up to 5 concurrently active agents. If you plan to replace Ona Automations that run many agents at once, review Licensing and usage.

Replace Automations

Ona Automations start agents from manual, pull request, schedule, and webhook triggers. In Coder, start agents with the Chats API from the system that owns the trigger:

Ona triggerWhere to call the Chats API
ManualThe Coder Agents chat interface, or a script
Pull requestA CI job that runs on pull request events
ScheduleA scheduled CI job or another scheduler
WebhookThe service that receives the webhook

Authenticate these calls with an API token for a service account (Premium). Refer to Use the API for programmatic automation for an example request.

To start agents from Slack or Linear, call the Chats API from those tools' webhook or automation features.

Set up auditing

Turn on Coder audit logs (Premium) to replace Ona audit logs. If you use AI Gateway (Premium), it records prompts, token usage, and tool invocations for each user. Agent Firewall (Premium) also streams agent network activity to the control plane.

Before you close your Ona organization, export any Ona audit logs that you must retain.

Pilot and cut over

  1. Run Coder and Ona side by side.
  2. Move one team and one project to Coder first.
  3. Compare workspace startup time and developer feedback with the same project on Ona.
  4. Move the remaining projects one at a time, starting with those that have the simplest .ona/config.yaml.
  5. Move each Automation after the projects it targets.
  6. After all developers and Automations move, remove your Ona runners and their cloud resources by following the Ona runner documentation.

Learn more