Skip to main content

Templates

View as MarkdownView llms.txt

A template is a reusable Remote Dev Environment configuration. Define the machine and its setup once, then create consistent sessions from it without repeating the same choices each time.

Template overviewClick to copy link​

A template can include:

  • A stack, a machine type, and a working directory that terminals start in.
  • Lifecycle hooks: setup scripts that run when the session is created, when someone gets it, and after every restore.
  • Variables and inputs for the values your environment needs.
  • Workspace links: shortcut buttons that open a specific folder in your IDE.
  • A virtual device: an iOS simulator or Android emulator that every session created from the template boots.

Lifecycle hooksClick to copy link​

A template sets up its sessions with lifecycle hooks. Each hook is a Bash script that runs as the session user, at one moment in the session's life:

  • On create runs once, when the session is created. Use it for slow, one-time setup, such as cloning and installing dependencies.
  • On claim runs when the session is assigned to someone. Use it for that person's own setup.
  • On restore runs every time a stopped session is restored. Use it to restart services.

Every hook is optional. Templates created before lifecycle hooks have a warmup script and a startup script instead. They keep working, and you can convert them.

Variables and inputsClick to copy link​

Templates carry two kinds of values:

  • Variables are stored on the template, with the same value for every session. Mark a variable as secret to encrypt it at rest, or as protected to also make it write-only.
  • Inputs are filled in for each session. You can mark an input as required and give it a default value. An input can also pull its value from a saved input, so secrets are resolved on the server and never shown in the UI.

Every variable and input belongs to a scope: Shared values reach every hook, and a hook's own values reach only that hook. Switch on Also in terminal to also make a value available in the session's terminal. See Variables and inputs.

Workspace links are buttons on the session that open a given folder path in your IDE. They're handy for jumping straight into the right directory in a multi-folder project.

Declared deviceClick to copy link​

A template can declare a virtual device, so every session created from it boots an iOS simulator or Android emulator without any device settings on the session. Turn on Boot a device with every session in the template form, or use the CLI:

bitrise-cli rde template create --file template.json --device-platform ios --device-model "iPhone 16"

The template's stack and machine type must fit the platform: a macOS stack for iOS, a Linux Android stack for Android. When you create a session from the template, you can keep the device as declared, change individual fields for that session only, or turn it off with Start an iOS simulator or Start an Android emulator in the UI and --no-device in the CLI. Sessions already created from the template keep the device they were created with. The device options themselves are described in Device sessions.

Managing templatesClick to copy link​

Create, edit, clone, and delete templates from the Bitrise RDE UI, or from the CLI with bitrise-cli rde template.

When you create a session, its template configuration is captured as a snapshot. Editing or deleting a template afterwards doesn't change or break sessions that were already created from it. This includes the hooks: a restore, running a failed hook again, and Rebuild all use the scripts the session was created with. To use a fixed script, create a new session.

Warm poolsClick to copy link​

To have sessions of a template ready before anyone asks for them, create a warm pool from it: Create warm pool on the template's page opens the pool form with the template selected. A pool follows its template, so editing the template replaces the pool's warm sessions, and deleting the template deletes its pools. To write a template that works well in a pool, see Using hooks with a warm pool.

See also