Overview

Prebuilds reduce environment startup times by pre-executing Dev Container lifecycle commands and automation tasks. Instead of installing dependencies and running build steps every time, prebuilds prepare a snapshot that is ready to use. A prebuild creates an environment, runs your Dev Container build process, lifecycle hooks (onCreateCommand and updateContentCommand), and automation tasks with the prebuild trigger. Once these commands complete, Ona snapshots the Dev Container filesystem. New environments start from this snapshot, skipping the setup steps.

​

Using prebuilds

When you create an environment, Ona uses a prebuild if one is available. Selection is best-effort:

• Matches your environment class (CPU, memory, storage)
• Uses the most recent successful prebuild
• Prebuilds expire after 7 days

If no matching prebuild exists, the environment starts normally without one.

​

What gets executed

During prebuild creation, Ona runs:

• Dev Container build: Builds your Dev Container image from the Dockerfile or docker-compose configuration. Prebuilds populate the Dev Container image cache, which speeds up subsequent builds.
• Dev Container lifecycle commands:
  • initializeCommand - Runs before the container is created
  • onCreateCommand - Runs when the container is created for the first time
  • updateContentCommand - Runs when the container is created or updated
• Automation tasks: Any tasks in your automations.yaml configured with the prebuild trigger. Organization and project secrets are available during these tasks, but user secrets are not.
• JetBrains warmup (optional): When enabled, downloads and installs the JetBrains backend and runs the warmup command to build project indexes. See JetBrains warmup for details.

​

What doesn’t run

The following commands do not run during prebuilds. They run when a user connects to the environment:

• postCreateCommand: runs after the environment is created
• postStartCommand: runs every time the environment starts
• postAttachCommand: runs when you attach to the environment

​

What gets included in the snapshot

The prebuild snapshot captures the entire Dev Container filesystem: installed dependencies, built artifacts, downloaded assets, and all file system changes made during prebuild execution. Nothing is excluded. Prebuilds use the same persistent storage model as regular environments.

​

Benefits

• Faster startup: Skip dependency installation and build steps
• Consistent environments: All team members start from the same state
• Lower resource usage: Build once, use many times

​

Runtime impact

Most prebuilds consume 5-10 minutes of runtime per project per day across the entire organization. They run once daily. Example: 20 engineers on a project, one 10-minute prebuild per day. Prebuilds account for about 2% of total runtime while making every engineer faster. Prebuilds trade a small amount of runtime to skip repetitive setup for your entire team.

​

How prebuilds work

1. Trigger: A prebuild starts on schedule or manual trigger
2. Environment creation: Ona creates a temporary environment from your project’s configuration
3. Command execution: Dev Container lifecycle commands and prebuild automation tasks run
4. Snapshot: Ona snapshots the environment once commands complete
5. Cleanup: The temporary environment is deleted
6. Usage: New environments start from the most recent successful snapshot

​

Prebuild lifecycle

Prebuilds go through several phases:

• Pending: Prebuild created, waiting to start
• Starting: Environment is being created
• Running: Commands and tasks are executing
• Stopping: Commands completed, environment is stopping
• Snapshotting: Creating a snapshot of the environment
• Completed: Prebuild successful, snapshot available
• Failed: Prebuild encountered an error

​

Secrets and authentication

During prebuild execution:

• Organization secrets: Available to all prebuilds
• Project secrets: Available to prebuilds for that project
• User secrets: Not available (prebuilds run without user context)

​

Prebuild executor

The executor determines which identity clones the repository and runs the prebuild. Configure it in project settings.

• User (default): The prebuild runs as the user who enabled prebuilds
• Service account: The prebuild runs as a service account, using the service account’s SCM credentials

Regardless of executor, no user secrets are used during prebuilds. Only organization and project secrets are available. When using a service account, configure SCM access on all runners where prebuilds run. See Git authentication for setup. Project admins can change the executor to themselves or a service account. If another user is the current executor, admins can leave it unchanged but cannot switch it to a different user. Best practice: Use service accounts so prebuilds keep working regardless of individual user availability.

​

Timeouts

If a prebuild exceeds its timeout, it fails. Failed prebuild environments remain available for debugging and are cleaned up after 7 days (or earlier based on environment archival settings).

​

Prebuild retention

• Prebuilds are deleted after 7 days
• Only the most recent successful prebuild per environment class is used
• Failed prebuilds are kept for debugging but do not affect environment creation

​

Pricing

​

Ona Cloud

• Environment usage: Standard usage-based billing for the time the prebuild environment runs
• Storage: Prebuild snapshots are free (this may change)

​

Enterprise (Your Cloud)

• Environment usage: You pay for compute resources used by the prebuild environment
• Storage: You pay for actual data stored in the snapshot. If you use 50 GB of a 100 GB volume, you are billed for 50 GB. Snapshots are stored as volume snapshots in your cloud provider (backed by S3).

See Billing for details.

​

Runner availability

Prebuilds are available on:

• AWS Enterprise runners: Requires updating your CloudFormation stack to the latest version
• Ona Cloud: Supported
• GCP Enterprise runners: Requires updating your Terraform stack to the latest version

​

JetBrains warmup

JetBrains warmup pre-installs the JetBrains backend and builds project indexes during prebuilds. Users skip the download and indexing time when they open a JetBrains editor.

​

What JetBrains warmup does

1. Backend pre-installation: Downloads and installs the JetBrains backend during the prebuild
2. Index building: Runs the warmup command to build project indexes (code analysis, symbol tables)

​

Enabling JetBrains warmup

1. Navigate to your project settings
2. In the prebuild configuration section, enable JetBrains warmup
3. Configure recommended editors to specify which JetBrains editors to warm up

​

Warmup execution order

JetBrains warmup runs after all other prebuild tasks complete. This means dependencies are installed and build artifacts are generated before indexing begins.

​

Use case: caching large file downloads

If your project downloads large assets (e.g. 20 GB+ of data files), configure a prebuild task to download them once. Subsequent environments start from the snapshot with the files already present, avoiding repeated downloads and reducing egress costs.

​

Warm pools

For projects where even prebuild-based startup is too slow (e.g. large monorepos with big EBS volumes), warm pools keep pre-initialized EC2 instances running and ready to claim. This significantly reduces environment startup time by skipping instance provisioning and snapshot restoration. Warm pools require the Enterprise plan and an AWS runner.

​

Limitations

• Prebuilds are tied to a specific environment class on a runner
• Only one prebuild per environment class is active at a time
• Only daily scheduling is available (more trigger options coming soon)
• Prebuilds cannot be triggered on every commit (coming soon)

​

Next steps

• Configure prebuilds for your project
• View and manage prebuilds
• Enable warm pools for faster startup times
• Learn about Dev Container configuration
• Explore Tasks and Services