[MrBlaise]

Documents lifecycle hooks for Remote Dev Environment templates: On create, On claim and On restore, the scripts that replace a template's warmup and startup scripts.

Draft on purpose. The pages describe the feature as released. Lifecycle hooks are still being rolled out workspace by workspace, and the CLI and MCP changes the pages refer to are in draft: bitrise-io/bitrise-cli#88 and bitrise-io/bitrise-mcp-dev-environments#53. Mark this ready once the rollout is complete and both are released.

New page

configuration/lifecycle-hooks.mdx:

• what each hook is for, and when it runs for a direct session and for a session claimed from a warm pool, including the platform's System setup step;
• writing a hook: runs as the session user, done when the script exits, long-running work in the background (env -u for secrets), no connections while On create runs, what survives a stop, hooks not waiting for a virtual device;
• variables and inputs: scopes (Shared or one hook), who fills them in, Plain / Secret / Protected, Also in terminal, and what someone claiming from a pool can see;
• using hooks with a warm pool, and the preview-link rule (no required On claim or On restore inputs);
• a worked iOS app example;
• following a session's setup: the Lifecycle card, its labels, per-hook logs, waiting for Ready instead of Running;
• failures: running a hook again, Rebuild, a pool's Setup failed state and Retry, and that both repeat the session's own script, so a template fix only reaches new sessions;
• converting a warmup/startup template (one way);
• CLI, AI agent (MCP) and API tabs.

Six screenshots in static/img/rde/, cropped to the relevant element and captured at 2x, 30–90 KB each.

Updated pages

• configuration/templates.mdx: lifecycle hooks replace the warmup and startup section; scopes and protected variables; a session's snapshot includes its hooks.
• configuration/warm-pools.mdx: a pool runs On create; the claim sets up the owner's credentials and runs On claim with their inputs; claim inputs in the UI, CLI and API; the Setup failed state.
• getting-started/key-concepts.mdx, getting-started/rde-faq.mdx, index.mdx (new card), devices/device-preview-links.mdx, rde-options/bitrise-rde-cli.mdx (log stages, run-hook, rebuild), rde-options/bitrise-rde-mcp-server.mdx, configuration/rde-api.mdx.
• migration/glossary.json and the glossary page: Lifecycle hook term, updated Template definition. static/llms.txt: new entry.
• Configuration sidebar renumbered so the page sits after Templates. No slugs changed, so no redirects are needed.

Checks

• docusaurus build --locale en passes, with no broken links or anchors on the RDE pages.
• I checked the rendered page at 390 px and 1440 px. There's no horizontal scrolling, and tables and code blocks fit. On a phone the screenshots open full size with the image zoom.
• The Japanese pages are left to the usual drift sync.

Before marking ready

• Lifecycle hooks are enabled for every workspace, and the CLI and MCP changes are released.
• The UI labels quoted on the page still match: Created from the template / Claimed from a warm pool, Run On claim again, Retry system setup, Rebuild, Setup failed, Retry, Convert to lifecycle hooks, Also in terminal.
• The API reference has synced the hook endpoints. The page doesn't link to generated pages that don't exist yet.

🤖 Generated with Claude Code

[MrBlaise]

This is a draft until we release the feature for all customers.

[github-actions]

Preview: https://docs-rde-lifecycle-hooks.bitrise-docs.pages.dev