From ab93cde4884d9f68ff4ed137f4df39a2a074717c Mon Sep 17 00:00:00 2001 From: Gabor Szakacs Date: Thu, 8 Oct 2026 15:32:31 +0200 Subject: [PATCH 1/4] Warm pools belong to the workspace Co-Authored-By: Claude Fable 5.1 --- docs/bitrise-rde/configuration/warm-pools.mdx | 34 +++++++++---------- .../rde-options/bitrise-rde-cli.mdx | 4 +-- .../rde-options/bitrise-rde-ui.mdx | 2 +- static/llms.txt | 2 +- 4 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/bitrise-rde/configuration/warm-pools.mdx b/docs/bitrise-rde/configuration/warm-pools.mdx index 360d9d14..a24d75f4 100644 --- a/docs/bitrise-rde/configuration/warm-pools.mdx +++ b/docs/bitrise-rde/configuration/warm-pools.mdx @@ -15,7 +15,7 @@ Warm pools are useful when a pool is needed immediately: an AI agent that needs ## How a warm pool works -A warm pool is a stored session configuration plus an owner and a pool size: +A warm pool is a stored session configuration plus a pool size, owned by the workspace: - The configuration is what a session create request carries: a template, its session input values, the enabled feature flags, and optional stack, machine type, cluster, and virtual device overrides. - The pool size is how many sessions the pool keeps booted. Bitrise creates them, runs the template's warmup and startup scripts on them, and keeps them ready. When one is claimed, a replacement boots to take its place. @@ -25,16 +25,15 @@ Claiming a session from a pool gives you one of its warm sessions, renamed and s Warm sessions are ordinary sessions underneath, and they cost machine time while they wait. They don't appear in anyone's session list, and until someone claims one it can't be connected to, changed, or terminated; you can read its logs from the pool page to check that the setup scripts do what you expect. A warm session has no auto-terminate timer of its own: it either gets claimed or is retired when the pool shrinks or its configuration changes. -## Personal and workspace pools +## Pools belong to the workspace -A pool belongs either to you or to the workspace: +A pool is shared with every member of the workspace: anyone with RDE access sees it, claims from it, and manages it, and a [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) can reach it from CI. Its inputs are stored as plain values, encrypted at rest when marked secret. [Saved inputs](/bitrise-rde/configuration/saved-inputs) are personal and can't be referenced from a pool, because there is no single person whose saved inputs it could use. -- A **personal pool** is private to you. Only you see it, claim from it, and manage it. Its inputs can reference your [saved inputs](/bitrise-rde/configuration/saved-inputs), so a rotated credential flows into the next warm sessions without editing the pool. -- A **workspace pool** is shared with every member of the workspace. Anyone with RDE access can claim from it and manage it, and a [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) can reach it from CI. Its inputs are stored as plain values, encrypted at rest when marked secret, because there is no single person whose saved inputs it could use. Only workspace pools can serve device preview links. +## Who owns a claimed session -A session claimed from a personal pool is owned by you, like a session you create yourself. +A session claimed from a pool is yours, like a session you create yourself: only you see and manage it. Until it's claimed, a warm session belongs to the workspace, so it's booted without anything personal on it, such as your saved inputs or your GitHub credential; add those yourself, over SSH for example. -A session claimed from a workspace pool is owned by the workspace: every member sees and manages it under **Workspace sessions**, and you're recorded as its creator. +To keep a claimed session shared instead, choose **Workspace** as the owner when claiming. Every member then sees and manages it under **Workspace sessions**, and you're recorded as its creator. Sessions claimed with a Workspace API token, and the device sessions a [preview link](/bitrise-rde/devices/device-preview-links) opens, are always owned by the workspace. Warm pools aren't available on free-trial workspaces. @@ -45,7 +44,7 @@ Warm pools aren't available on free-trial workspaces. 1. In the Remote Dev Environments section, open **Warm pools** and click **New warm pool**. From a template's page, **Create warm pool** opens the same form with the template already selected. 1. Choose the template. The form then shows only what the template calls for: session inputs, feature flags, a device section when the template boots one, and the same **Override machine configuration** switch the session form has. -1. Enter a **Pool name** and choose the owner: **Me** for a personal pool or **Workspace** for a shared one. +1. Enter a **Pool name**. 1. Set the **Pool size**. 1. Click **Create warm pool**. @@ -55,15 +54,15 @@ The pool page shows how many sessions are ready and how many are still warming u ```bash -bitrise-cli rde warm-pool create ios-reviewers --template "iOS Xcode 26" --size 2 --owner workspace +bitrise-cli rde warm-pool create ios-reviewers --template "iOS Xcode 26" --size 2 ``` -`--input`, `--secret-input`, and `--saved-input` set the template's session inputs, `--feature-flag` enables a template feature flag, and the `--stack`, `--machine-type`, and `--device-*` flags override what the template declares. Every command that takes a pool ID also accepts the pool's name. +`--input` and `--secret-input` set the template's session inputs, `--feature-flag` enables a template feature flag, and the `--stack`, `--machine-type`, and `--device-*` flags override what the template declares. Every command that takes a pool ID also accepts the pool's name. -Ask for it in plain language, for example: *"Keep two sessions of the iOS Xcode 26 template warm for the team."* The agent calls `bitrise_devenv_create_warm_pool` with the template, the inputs, the owner, and the pool size. +Ask for it in plain language, for example: *"Keep two sessions of the iOS Xcode 26 template warm for the team."* The agent calls `bitrise_devenv_create_warm_pool` with the template, the inputs, and the pool size. @@ -75,7 +74,6 @@ curl -X POST "https://api.bitrise.io/rde/v1/workspaces/WORKSPACE_ID/warm-pools" -d '{ "name": "ios-reviewers", "template_id": "TEMPLATE_ID", - "owner_type": "workspace", "pool_size": 2 }' ``` @@ -92,7 +90,7 @@ The configuration is validated the same way a session create is: an unknown inpu -On the **New session** form, once a template and an owner are chosen, **Start from warm pool** lists the matching pools; when exactly one matches, it's preselected. With a pool selected the configuration sections are fixed by the pool, and you only name the session and set its auto-terminate window. A pool's page also has a **Claim a session** button that opens the form with the pool preselected. +On the **New session** form, once a template is chosen, **Start from warm pool** lists its pools; when there is exactly one, it's preselected. With a pool selected the configuration sections are fixed by the pool, and you only name the session, choose its owner (**Me** by default), and set its auto-terminate window. A pool's page also has a **Claim a session** button that opens the form with the pool preselected. @@ -121,13 +119,13 @@ The pool fixes the configuration, so a claim can't also pass a template, inputs, Bitrise checks every pool regularly and keeps it at its size. A few things to know: - **Editing the configuration replaces the warm sessions.** Changing the inputs, the flags, or the machine or device settings retires the sessions that were warmed with the old configuration and boots new ones. The UI warns you before saving such a change. Renaming the pool or changing its size doesn't touch the warm sessions. -- **A template edit does the same.** The pool follows its template, so editing the template's scripts or variables replaces the pool's warm sessions too. Rotating a saved input a personal pool references has the same effect. +- **A template edit does the same.** The pool follows its template, so editing the template's scripts or variables replaces the pool's warm sessions too. - **A configuration that stops working pauses the pool.** If a template edit adds a required input the pool doesn't have, or removes a feature flag it enables, the pool shows a configuration error and stops creating sessions until you fix it. The warm sessions it already has stay claimable. - **Repeated failures pause the pool** for a while before it retries, so a broken setup script doesn't burn machines in a loop. The pool page shows the last error. ## Scaling a pool on a schedule -Warm sessions cost machine time while idle, so keep the size at what demand needs. The size is one call, which makes a schedule easy: warm the pool up for business hours and drain it in the evening. For a workspace pool, a Workspace API token in a cron job does it: +Warm sessions cost machine time while idle, so keep the size at what demand needs. The size is one call, which makes a schedule easy: warm the pool up for business hours and drain it in the evening. A Workspace API token in a cron job does it: ```bash 0 8 * * 1-5 BITRISE_TOKEN=bitwat_… bitrise-cli rde warm-pool set-size ios-reviewers 3 --workspace WORKSPACE_ID -q @@ -138,12 +136,12 @@ A size of 0 retires every warm session but keeps the pool, its configuration, an ## Device pools and preview links -A pool of a template that boots a virtual device keeps devices booted too, which is what makes a [device preview link](/bitrise-rde/devices/device-preview-links) open in the time it takes to download the app. Mint the link against a workspace pool, and every open claims one of its warm devices. See [Serving links from a warm pool](/bitrise-rde/devices/device-preview-links#serving-links-from-a-warm-pool). +A pool of a template that boots a virtual device keeps devices booted too, which is what makes a [device preview link](/bitrise-rde/devices/device-preview-links) open in the time it takes to download the app. Mint the link against the pool, and every open claims one of its warm devices. See [Serving links from a warm pool](/bitrise-rde/devices/device-preview-links#serving-links-from-a-warm-pool). A claim from a device pool can install an app build right away: pass the build's URL as the session's artifact, and it installs the moment the session is handed out, because the device is already running. ## Managing pools -The **Warm pools** page lists your pools under **My pools** and the shared ones under **Workspace pools**. From a pool's page you can change its size, edit its configuration, claim a session, and delete it. The CLI mirrors this with `bitrise-cli rde warm-pool list`, `view`, `update`, `set-size`, and `delete`, and the [API](/bitrise-rde/configuration/rde-api#warm-pools) with the warm pool endpoints. +The **Warm pools** page lists the workspace's pools. From a pool's page you can change its size, edit its configuration, claim a session, and delete it. The CLI mirrors this with `bitrise-cli rde warm-pool list`, `view`, `update`, `set-size`, and `delete`, and the [API](/bitrise-rde/configuration/rde-api#warm-pools) with the warm pool endpoints. -Workspace owners and members who manage billing see every pool in the workspace, including other members' personal pools, on the **Usage** page and with `bitrise-cli rde warm-pool list --all`. That view is read-only: only a pool's owner manages it. +Workspace owners and members who manage billing also see every pool with its size on the **Usage** page and with `bitrise-cli rde warm-pool list --all`, next to the rest of the workspace's RDE spend. diff --git a/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx b/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx index 3ee34f7c..6aa1eb26 100644 --- a/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx +++ b/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx @@ -127,14 +127,14 @@ The CLI covers both ways to use [virtual devices](/bitrise-rde/devices/virtual-d | Command | What it does | | --- | --- | -| `bitrise-cli rde warm-pool create NAME --template TEMPLATE --size N` | Create a pool. Add `--owner workspace` for a shared pool, `--input`, `--secret-input`, and `--saved-input` for the template's inputs, and the `--stack`, `--machine-type`, and `--device-*` flags to override the template. | +| `bitrise-cli rde warm-pool create NAME --template TEMPLATE --size N` | Create a pool. Add `--input` and `--secret-input` for the template's inputs, and the `--stack`, `--machine-type`, and `--device-*` flags to override the template. | | `bitrise-cli rde warm-pool list` | List your pools and the workspace's, with their size and how many sessions are ready. `--all` shows every pool in the workspace, read-only. | | `bitrise-cli rde warm-pool view WARM_POOL_ID` | Show a pool's status, configuration, and warm sessions. | | `bitrise-cli rde warm-pool set-size WARM_POOL_ID N` | Change how many sessions the pool keeps booted. `0` drains it but keeps the configuration. | | `bitrise-cli rde warm-pool update WARM_POOL_ID` | Rename a pool or change its configuration. A configuration change replaces the warm sessions. | | `bitrise-cli rde warm-pool delete WARM_POOL_ID` | Delete a pool and its warm sessions. | | `bitrise-cli rde session create NAME --warm-pool WARM_POOL_ID` | Claim a session from a pool. | -| `bitrise-cli rde preview-link create --warm-pool WARM_POOL_ID --artifact-url URL` | Mint a device preview link whose opens are served from a workspace pool. | +| `bitrise-cli rde preview-link create --warm-pool WARM_POOL_ID --artifact-url URL` | Mint a device preview link whose opens are served from a warm pool. | ## Templates, saved inputs, and machine options diff --git a/docs/bitrise-rde/rde-options/bitrise-rde-ui.mdx b/docs/bitrise-rde/rde-options/bitrise-rde-ui.mdx index cb149434..e18f847a 100644 --- a/docs/bitrise-rde/rde-options/bitrise-rde-ui.mdx +++ b/docs/bitrise-rde/rde-options/bitrise-rde-ui.mdx @@ -62,7 +62,7 @@ You can create and manage reusable session configurations from the UI: see [Temp ## Warm pools -The **Warm pools** page lists the pools that keep sessions booted for you (**My pools**) and for the whole workspace (**Workspace pools**). Create one with **New warm pool**, and from a pool's page change its size, edit its configuration, claim a session, or delete it. See [Warm pools](/bitrise-rde/configuration/warm-pools). +The **Warm pools** page lists the pools that keep sessions booted for the workspace. Create one with **New warm pool**, and from a pool's page change its size, edit its configuration, claim a session, or delete it. See [Warm pools](/bitrise-rde/configuration/warm-pools). ## Workspace usage diff --git a/static/llms.txt b/static/llms.txt index 4176cfd2..8dc10bea 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -60,7 +60,7 @@ Every documentation page is also available as plain markdown: take the page path - [Virtual devices](https://docs.bitrise.io/bitrise-rde/devices/virtual-devices.md): iOS simulators and Android emulators on RDE: device sessions vs. device preview links, supported platforms and builds. - [Device sessions](https://docs.bitrise.io/bitrise-rde/devices/device-sessions.md): Creating a session that boots a simulator or emulator (UI, CLI, MCP, API), device readiness, driving it, and the agent guides. - [Device preview links](https://docs.bitrise.io/bitrise-rde/devices/device-preview-links.md): Sharing an app build as a browser link with no login; the Device Preview CI Step, CLI, MCP, API, limits. -- [Warm pools](https://docs.bitrise.io/bitrise-rde/configuration/warm-pools.md): Keeping pre-booted sessions ready to claim in seconds (UI, CLI, MCP, API), personal vs. workspace pools, scaling on a schedule, and serving device preview links from a pool. +- [Warm pools](https://docs.bitrise.io/bitrise-rde/configuration/warm-pools.md): Keeping pre-booted sessions ready to claim in seconds (UI, CLI, MCP, API), who owns a claimed session, scaling on a schedule, and serving device preview links from a pool. - [GitHub integration](https://docs.bitrise.io/bitrise-rde/configuration/github-integration.md): Automatic git and GitHub CLI authentication in sessions via the Bitrise GitHub App. - [Managing RDE access](https://docs.bitrise.io/bitrise-rde/configuration/managing-rde-access.md): Granting and revoking the RDE User role for workspace members and groups, and via SCIM. - [RDE API](https://docs.bitrise.io/bitrise-rde/configuration/rde-api.md): Programmatic RDE operations. From 04736d15e40322d828e957816e0208993a7b26e9 Mon Sep 17 00:00:00 2001 From: Gabor Szakacs Date: Thu, 8 Oct 2026 16:02:02 +0200 Subject: [PATCH 2/4] Mark warm pools as an alpha feature Co-Authored-By: Claude Fable 5.1 --- docs/bitrise-rde/configuration/warm-pools.mdx | 6 ++++++ docs/bitrise-rde/getting-started/key-concepts.mdx | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/bitrise-rde/configuration/warm-pools.mdx b/docs/bitrise-rde/configuration/warm-pools.mdx index a24d75f4..5004fabc 100644 --- a/docs/bitrise-rde/configuration/warm-pools.mdx +++ b/docs/bitrise-rde/configuration/warm-pools.mdx @@ -13,6 +13,12 @@ A warm pool keeps a number of warm pool keeps a number of sessions of one configuration booted and idle, so creating a session from it takes seconds: the session is claimed from the pool instead of booting a fresh machine, and the pool boots a replacement. A pool stores a template with its inputs and overrides, belongs to you or to the workspace, and has a pool size you can change at any time, including on a schedule. -For details, see [Warm pools](/bitrise-rde/configuration/warm-pools). +Warm pools are in alpha and can change in backwards-incompatible ways. For details, see [Warm pools](/bitrise-rde/configuration/warm-pools). ## Saved inputs From a19a495e4c9fac81ef73b7b232ff03383c813d5d Mon Sep 17 00:00:00 2001 From: Ilana Zholobovsky Date: Fri, 9 Oct 2026 08:32:18 +0200 Subject: [PATCH 3/4] Remove the last personal-pool references Pools belong to the workspace now, so drop the leftover ownership wording on the key concepts, device preview links, and CLI pages. The CLI table's `warm-pool list --all` description now matches the API spec: a read-only cost view of the same pools for billing managers. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01NheGCZkEkSqVsG6hmR8yMA --- docs/bitrise-rde/devices/device-preview-links.mdx | 2 +- docs/bitrise-rde/getting-started/key-concepts.mdx | 2 +- docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/bitrise-rde/devices/device-preview-links.mdx b/docs/bitrise-rde/devices/device-preview-links.mdx index d245c366..64ad7f71 100644 --- a/docs/bitrise-rde/devices/device-preview-links.mdx +++ b/docs/bitrise-rde/devices/device-preview-links.mdx @@ -145,7 +145,7 @@ The link-specific options: Without a pool, every open of a link starts a new session from scratch: a machine is provisioned, the session's setup runs, the simulator or emulator boots, and only then does the app download and install. That startup is most of the one to three minutes a reviewer waits. A [warm pool](/bitrise-rde/configuration/warm-pools) removes it: mint the link against a pool of a template that boots the app's device, and every open claims one of the pool's warm sessions, already running with its device up, so the click-to-app time is the app download. When the pool has no warm session at that moment, the open creates one from the pool's configuration, so the link still works, just slower. -The pool must be workspace-owned, because a link is shared with people outside Bitrise, and its configuration must boot a device of the app's platform. The pool fixes the device and the machine: leave the device model, OS version, system image, emulator sizing, stack, and machine type unset when minting against a pool. The app's platform is still checked, so an Android build can't be minted against an iOS pool. +The pool's configuration must boot a device of the app's platform. The pool fixes the device and the machine: leave the device model, OS version, system image, emulator sizing, stack, and machine type unset when minting against a pool. The app's platform is still checked, so an Android build can't be minted against an iOS pool. In the Device Preview Step, set `warm_pool_id` to the pool's ID. Copy it from the pool's page in the RDE UI, or from `bitrise-cli rde warm-pool view`: diff --git a/docs/bitrise-rde/getting-started/key-concepts.mdx b/docs/bitrise-rde/getting-started/key-concepts.mdx index 91651256..cf4a8d59 100644 --- a/docs/bitrise-rde/getting-started/key-concepts.mdx +++ b/docs/bitrise-rde/getting-started/key-concepts.mdx @@ -63,7 +63,7 @@ For details, see [Templates](/bitrise-rde/configuration/templates). ## Warm pools -A warm pool keeps a number of sessions of one configuration booted and idle, so creating a session from it takes seconds: the session is claimed from the pool instead of booting a fresh machine, and the pool boots a replacement. A pool stores a template with its inputs and overrides, belongs to you or to the workspace, and has a pool size you can change at any time, including on a schedule. +A warm pool keeps a number of sessions of one configuration booted and idle, so creating a session from it takes seconds: the session is claimed from the pool instead of booting a fresh machine, and the pool boots a replacement. A pool stores a template with its inputs and overrides, belongs to the workspace, and has a pool size you can change at any time, including on a schedule. Warm pools are in alpha and can change in backwards-incompatible ways. For details, see [Warm pools](/bitrise-rde/configuration/warm-pools). diff --git a/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx b/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx index 6aa1eb26..cb4a4cc1 100644 --- a/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx +++ b/docs/bitrise-rde/rde-options/bitrise-rde-cli.mdx @@ -128,7 +128,7 @@ The CLI covers both ways to use [virtual devices](/bitrise-rde/devices/virtual-d | Command | What it does | | --- | --- | | `bitrise-cli rde warm-pool create NAME --template TEMPLATE --size N` | Create a pool. Add `--input` and `--secret-input` for the template's inputs, and the `--stack`, `--machine-type`, and `--device-*` flags to override the template. | -| `bitrise-cli rde warm-pool list` | List your pools and the workspace's, with their size and how many sessions are ready. `--all` shows every pool in the workspace, read-only. | +| `bitrise-cli rde warm-pool list` | List the workspace's pools, with their size and how many sessions are ready. `--all` is the read-only cost view of the same pools, for workspace owners and members who manage billing. | | `bitrise-cli rde warm-pool view WARM_POOL_ID` | Show a pool's status, configuration, and warm sessions. | | `bitrise-cli rde warm-pool set-size WARM_POOL_ID N` | Change how many sessions the pool keeps booted. `0` drains it but keeps the configuration. | | `bitrise-cli rde warm-pool update WARM_POOL_ID` | Rename a pool or change its configuration. A configuration change replaces the warm sessions. | From 10430738d6786ff2cba1b66df6bbc60054626376 Mon Sep 17 00:00:00 2001 From: Ilana Zholobovsky Date: Fri, 9 Oct 2026 15:44:48 +0200 Subject: [PATCH 4/4] Tighten the warm pools prose Shorter sentences, one idea each, explicit subjects instead of "it" and "them", lists for parallel cases, active voice, no semicolons, no idioms. The free-trial note moves up next to the use cases. No claim changes. Longest sentence drops from 42 to 27 words. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01NheGCZkEkSqVsG6hmR8yMA --- docs/bitrise-rde/configuration/warm-pools.mdx | 64 ++++++++++--------- .../getting-started/key-concepts.mdx | 2 +- 2 files changed, 36 insertions(+), 30 deletions(-) diff --git a/docs/bitrise-rde/configuration/warm-pools.mdx b/docs/bitrise-rde/configuration/warm-pools.mdx index 5004fabc..45324990 100644 --- a/docs/bitrise-rde/configuration/warm-pools.mdx +++ b/docs/bitrise-rde/configuration/warm-pools.mdx @@ -9,39 +9,45 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import GlossTerm from '@site/src/components/GlossTerm'; -A warm pool keeps a number of RDE sessions booted and idle, so that creating a session takes seconds instead of the minutes a fresh machine needs to boot and run its setup. You describe the session once, the way you would when creating one, and set a pool size. Bitrise keeps that many sessions warm, and hands one out when someone asks for it. +A warm pool keeps a set number of RDE sessions booted and idle. Creating a session from the pool takes seconds, instead of the minutes a fresh machine needs to boot and run its setup. You describe the session once, as you would when creating one, and set a pool size. Bitrise keeps that many sessions warm and hands one out on request. -Warm pools are useful when a pool is needed immediately: an AI agent that needs a machine now, a team that starts many similar sessions a day, and [device preview links](/bitrise-rde/devices/device-preview-links) where a reviewer clicks and expects the app on screen. +Use a warm pool when you need sessions right away, for example: + +- An AI agent that needs a machine now. +- A team that starts many similar sessions a day. +- A [device preview link](/bitrise-rde/devices/device-preview-links), where a reviewer clicks and expects the app on screen. + +Warm pools aren't available on free-trial workspaces. :::warning[Alpha feature] -Warm pools are in alpha, as the **Alpha** badge in the RDE UI shows. How pools are configured, how a claimed session is personalized, and the related CLI commands, MCP tools, and API endpoints can change in backwards-incompatible ways without notice. Expect to adjust your templates, scripts, and automation as the feature evolves. +Warm pools are in alpha, as the **Alpha** badge in the RDE UI shows. Pool configuration, the way a claimed session is personalized, and the related CLI commands, MCP tools, and API endpoints can change in backwards-incompatible ways without notice. Expect to adjust your templates, scripts, and automation. ::: ## How a warm pool works -A warm pool is a stored session configuration plus a pool size, owned by the workspace: +A warm pool has two parts: a stored session configuration and a pool size. The workspace owns the pool. -- The configuration is what a session create request carries: a template, its session input values, the enabled feature flags, and optional stack, machine type, cluster, and virtual device overrides. -- The pool size is how many sessions the pool keeps booted. Bitrise creates them, runs the template's warmup and startup scripts on them, and keeps them ready. When one is claimed, a replacement boots to take its place. -- A pool with a size of 0 keeps no sessions but stays around as a configuration preset: claiming from it creates a session from the stored configuration. +- The configuration holds the same fields as a session create request: a template, its session input values, the enabled feature flags, and optional overrides for stack, machine type, cluster, and virtual device. +- The pool size is how many sessions the pool keeps booted. Bitrise creates the sessions, runs the template's warmup and startup scripts on them, and keeps them ready. When someone claims one, a replacement boots. +- A pool with size 0 keeps no sessions but still works as a configuration preset. Claiming from it creates a session from the stored configuration. -Claiming a session from a pool gives you one of its warm sessions, renamed and stamped with your name, labels, and auto-terminate window. If none is ready yet, you get one that's still warming up, and it finishes starting under your name. If no warm session is available at that moment, a session is created from the pool's configuration instead. Every session records where it came from: a claimed session's warm state is `claimed`, a session created on demand from the pool is `cold`. In the RDE UI, the session list shows these as **Claimed** and **Built cold** badges. +When you claim a session, you get one of the pool's warm sessions. Bitrise renames it and applies your name, labels, and auto-terminate window. If no session is ready yet, you get one that is still warming up, and it finishes starting as your session. If the pool has no warm session at all, Bitrise creates a session from the pool's configuration instead. Every session records where it came from: a claimed session has the warm state `claimed`, and a session created on demand has the warm state `cold`. The session list in the RDE UI shows these as **Claimed** and **Built cold** badges. -Warm sessions are ordinary sessions underneath, and they cost machine time while they wait. They don't appear in anyone's session list, and until someone claims one it can't be connected to, changed, or terminated; you can read its logs from the pool page to check that the setup scripts do what you expect. A warm session has no auto-terminate timer of its own: it either gets claimed or is retired when the pool shrinks or its configuration changes. +A warm session is a regular session that waits to be claimed, and it costs machine time while it waits. Until someone claims it, it doesn't appear in any session list, and nobody can connect to it, change it, or terminate it. You can read its logs on the pool page to check that the setup scripts work. A warm session has no auto-terminate timer. It waits until someone claims it, or until Bitrise retires it because the pool shrank or its configuration changed. -## Pools belong to the workspace +## Who can use a pool -A pool is shared with every member of the workspace: anyone with RDE access sees it, claims from it, and manages it, and a [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) can reach it from CI. Its inputs are stored as plain values, encrypted at rest when marked secret. [Saved inputs](/bitrise-rde/configuration/saved-inputs) are personal and can't be referenced from a pool, because there is no single person whose saved inputs it could use. +Every member of the workspace with RDE access sees the pool, claims from it, and manages it. A [Workspace API token](/bitrise-platform/workspaces/workspace-api-token) can reach it from CI. -## Who owns a claimed session +The pool's inputs are stored as plain values, encrypted at rest when marked secret. [Saved inputs](/bitrise-rde/configuration/saved-inputs) are personal, so a pool can't reference them: there is no single person whose saved inputs it could use. -A session claimed from a pool is yours, like a session you create yourself: only you see and manage it. Until it's claimed, a warm session belongs to the workspace, so it's booted without anything personal on it, such as your saved inputs or your GitHub credential; add those yourself, over SSH for example. +## Who owns a claimed session -To keep a claimed session shared instead, choose **Workspace** as the owner when claiming. Every member then sees and manages it under **Workspace sessions**, and you're recorded as its creator. Sessions claimed with a Workspace API token, and the device sessions a [preview link](/bitrise-rde/devices/device-preview-links) opens, are always owned by the workspace. +A session claimed from a pool is yours, like a session you create yourself: only you see and manage it. A warm session is booted before anyone claims it, so it has nothing personal on it: no saved inputs, no GitHub credential. Add those after claiming, for example over SSH. -Warm pools aren't available on free-trial workspaces. +To share a claimed session instead, choose **Workspace** as the owner when you claim it. Every member then sees and manages it under **Workspace sessions**, with you recorded as its creator. Sessions claimed with a Workspace API token, and the device sessions a [preview link](/bitrise-rde/devices/device-preview-links) opens, always belong to the workspace. ## Creating a pool @@ -49,12 +55,12 @@ Warm pools aren't available on free-trial workspaces. 1. In the Remote Dev Environments section, open **Warm pools** and click **New warm pool**. From a template's page, **Create warm pool** opens the same form with the template already selected. -1. Choose the template. The form then shows only what the template calls for: session inputs, feature flags, a device section when the template boots one, and the same **Override machine configuration** switch the session form has. +1. Choose the template. The form shows only what the template needs: session inputs, feature flags, a device section if the template boots a device, and the same **Override machine configuration** switch as the session form. 1. Enter a **Pool name**. 1. Set the **Pool size**. 1. Click **Create warm pool**. -The pool page shows how many sessions are ready and how many are still warming up, the warm sessions by name, and lifetime counts of claimed and cold sessions. +The pool page shows how many sessions are ready and how many are still warming up. It also lists the warm sessions by name, and lifetime counts of claimed and cold sessions. @@ -89,14 +95,14 @@ The configuration fields are the same as the create session request's. See [Crea -The configuration is validated the same way a session create is: an unknown input, a missing required input, or a device the machine type can't run is rejected when you save. Warm sessions are running sessions and count toward your workspace's session limit, the same as sessions people create. If a pool can't reach its size because the workspace is at its limit, its page shows the error and the pool keeps trying. +Bitrise validates the configuration the same way as a session create request. An unknown input, a missing required input, or a device the machine type can't run is rejected when you save. Warm sessions are running sessions, so they count toward the workspace's session limit like any other session. If the workspace is at its limit and the pool can't reach its size, the pool page shows the error and the pool keeps trying. ## Claiming a session -On the **New session** form, once a template is chosen, **Start from warm pool** lists its pools; when there is exactly one, it's preselected. With a pool selected the configuration sections are fixed by the pool, and you only name the session, choose its owner (**Me** by default), and set its auto-terminate window. A pool's page also has a **Claim a session** button that opens the form with the pool preselected. +On the **New session** form, once you choose a template, **Start from warm pool** lists its pools and preselects the pool when there is only one. With a pool selected, the pool fixes the configuration sections. You only name the session, choose its owner (**Me** by default), and set its auto-terminate window. A pool's page also has a **Claim a session** button that opens the form with the pool preselected. @@ -108,7 +114,7 @@ bitrise-cli rde session create my-fix --warm-pool ios-reviewers -The agent passes `warm_pool_id` to `bitrise_devenv_create`; `bitrise_devenv_list_warm_pools` shows it which pools it can claim from. +The agent passes `warm_pool_id` to `bitrise_devenv_create`. To see which pools it can claim from, it calls `bitrise_devenv_list_warm_pools`. @@ -118,36 +124,36 @@ Set `warm_pool_id` on the create session request and leave the configuration fie -The pool fixes the configuration, so a claim can't also pass a template, inputs, feature flags, a stack, machine type, cluster, or device: those are rejected, not ignored. What you still choose per session: the name, description, labels, the auto-terminate window, and for a pool that boots a device, an app build to install. +The pool fixes the configuration. A claim that also passes a template, inputs, feature flags, a stack, a machine type, a cluster, or a device is rejected, not ignored. Per session, you still choose the name, description, labels, and auto-terminate window. For a pool that boots a device, you can also choose an app build to install. ## Keeping the pool healthy Bitrise checks every pool regularly and keeps it at its size. A few things to know: -- **Editing the configuration replaces the warm sessions.** Changing the inputs, the flags, or the machine or device settings retires the sessions that were warmed with the old configuration and boots new ones. The UI warns you before saving such a change. Renaming the pool or changing its size doesn't touch the warm sessions. +- **Editing the configuration replaces the warm sessions.** When you change the inputs, the feature flags, or the machine or device settings, Bitrise retires the sessions warmed with the old configuration and boots new ones. The UI warns you before you save such a change. Renaming the pool or changing its size doesn't affect the warm sessions. - **A template edit does the same.** The pool follows its template, so editing the template's scripts or variables replaces the pool's warm sessions too. -- **A configuration that stops working pauses the pool.** If a template edit adds a required input the pool doesn't have, or removes a feature flag it enables, the pool shows a configuration error and stops creating sessions until you fix it. The warm sessions it already has stay claimable. -- **Repeated failures pause the pool** for a while before it retries, so a broken setup script doesn't burn machines in a loop. The pool page shows the last error. +- **A broken configuration pauses the pool.** A template edit can add a required input the pool doesn't set, or remove a feature flag the pool enables. The pool then shows a configuration error and stops creating sessions until you fix it. The pool's existing warm sessions stay claimable. +- **Repeated failures pause the pool.** The pool waits a while before it retries, so a broken setup script doesn't keep starting new machines. The pool page shows the last error. ## Scaling a pool on a schedule -Warm sessions cost machine time while idle, so keep the size at what demand needs. The size is one call, which makes a schedule easy: warm the pool up for business hours and drain it in the evening. A Workspace API token in a cron job does it: +Warm sessions cost machine time while idle, so keep the pool size at what demand needs. Changing the size is a single call, which makes a schedule easy: warm the pool up for business hours and drain it in the evening. A cron job with a Workspace API token does it: ```bash 0 8 * * 1-5 BITRISE_TOKEN=bitwat_… bitrise-cli rde warm-pool set-size ios-reviewers 3 --workspace WORKSPACE_ID -q 0 19 * * 1-5 BITRISE_TOKEN=bitwat_… bitrise-cli rde warm-pool set-size ios-reviewers 0 --workspace WORKSPACE_ID -q ``` -A size of 0 retires every warm session but keeps the pool, its configuration, and any preview links minted with it. Deleting the pool also retires its warm sessions, and additionally invalidates its preview links. Sessions already claimed from the pool are regular sessions and aren't affected by either. +Size 0 retires every warm session but keeps the pool, its configuration, and any preview links minted with it. Deleting the pool retires its warm sessions and also invalidates its preview links. Sessions already claimed from the pool are regular sessions, and neither change affects them. ## Device pools and preview links -A pool of a template that boots a virtual device keeps devices booted too, which is what makes a [device preview link](/bitrise-rde/devices/device-preview-links) open in the time it takes to download the app. Mint the link against the pool, and every open claims one of its warm devices. See [Serving links from a warm pool](/bitrise-rde/devices/device-preview-links#serving-links-from-a-warm-pool). +If the pool's template boots a virtual device, the pool keeps devices booted too. This is why a [device preview link](/bitrise-rde/devices/device-preview-links) opens in the time it takes to download the app. Mint the link against the pool, and every open claims one of its warm devices. See [Serving links from a warm pool](/bitrise-rde/devices/device-preview-links#serving-links-from-a-warm-pool). -A claim from a device pool can install an app build right away: pass the build's URL as the session's artifact, and it installs the moment the session is handed out, because the device is already running. +A claim from a device pool can install an app build right away. Pass the build's URL as the session's artifact. Because the device is already running, the app installs the moment the session is handed out. ## Managing pools The **Warm pools** page lists the workspace's pools. From a pool's page you can change its size, edit its configuration, claim a session, and delete it. The CLI mirrors this with `bitrise-cli rde warm-pool list`, `view`, `update`, `set-size`, and `delete`, and the [API](/bitrise-rde/configuration/rde-api#warm-pools) with the warm pool endpoints. -Workspace owners and members who manage billing also see every pool with its size on the **Usage** page and with `bitrise-cli rde warm-pool list --all`, next to the rest of the workspace's RDE spend. +Workspace owners and members who manage billing also see every pool and its size. The pools appear on the **Usage** page and in `bitrise-cli rde warm-pool list --all`, alongside the rest of the workspace's RDE spend. diff --git a/docs/bitrise-rde/getting-started/key-concepts.mdx b/docs/bitrise-rde/getting-started/key-concepts.mdx index cf4a8d59..bf76700d 100644 --- a/docs/bitrise-rde/getting-started/key-concepts.mdx +++ b/docs/bitrise-rde/getting-started/key-concepts.mdx @@ -63,7 +63,7 @@ For details, see [Templates](/bitrise-rde/configuration/templates). ## Warm pools -A warm pool keeps a number of sessions of one configuration booted and idle, so creating a session from it takes seconds: the session is claimed from the pool instead of booting a fresh machine, and the pool boots a replacement. A pool stores a template with its inputs and overrides, belongs to the workspace, and has a pool size you can change at any time, including on a schedule. +A warm pool keeps a number of sessions of one configuration booted and idle. Creating a session from the pool takes seconds: the session is claimed from the pool instead of booting a fresh machine, and the pool boots a replacement. A pool stores a template with its inputs and overrides, belongs to the workspace, and has a pool size you can change at any time, including on a schedule. Warm pools are in alpha and can change in backwards-incompatible ways. For details, see [Warm pools](/bitrise-rde/configuration/warm-pools).