From bc9a147c7f74a20b8fa7bf14e39741976c47d538 Mon Sep 17 00:00:00 2001 From: Matt Rubens <2600+mrubens@users.noreply.github.com> Date: Fri, 7 Aug 2026 23:53:40 +0000 Subject: [PATCH 1/2] docs: explain source-controlled environment definitions --- SELF_HOSTING.md | 7 ++-- apps/docs/environments.mdx | 18 ++++----- apps/docs/environments/definition.mdx | 58 +++++++++++++++++++++++++++ 3 files changed, 70 insertions(+), 13 deletions(-) diff --git a/SELF_HOSTING.md b/SELF_HOSTING.md index cccad65c9..56308653b 100644 --- a/SELF_HOSTING.md +++ b/SELF_HOSTING.md @@ -861,10 +861,9 @@ Semantics: to normal manual management; it keeps all data and loses only the badge. - Renaming `name` inside a definition creates a new environment under the new name and orphans the old one. -- Definitions may reference repositories that are not linked to the - deployment yet (for example before the GitHub App is installed). The - environment is created anyway and repository mappings backfill on the next - startup after the repositories are linked. +- Repositories in a definition must already be linked to the deployment. + Definitions with missing repository mappings are skipped with a logged error + and retried on the next startup. - Invalid definitions are skipped with a logged error; they never prevent the API from starting or other definitions from applying. A missing or unreadable definitions directory is skipped the same way, so inline diff --git a/apps/docs/environments.mdx b/apps/docs/environments.mdx index e6272e8c5..a54211cc7 100644 --- a/apps/docs/environments.mdx +++ b/apps/docs/environments.mdx @@ -224,15 +224,15 @@ on the next restart (every overwrite is kept in version history). Removing a definition never deletes the environment; it just returns it to normal manual management. -Definitions may reference repositories that are not linked yet; the -environment is created anyway and repository mappings backfill on the next -startup after linking. Keep secrets out of definition files — the -per-environment `env` map is stored in plaintext, so use deployment -environment variables under **Settings > Environments > Deployment Environment -Variables** for secret values. - -See the [self-hosting guide](/self-hosting) for the compose mount pattern and -operational details. +Repositories in a definition must already be linked to the deployment. Roomote +skips definitions with missing repository mappings, logs the reason, and tries +them again on the next startup. Keep secrets out of definition files — the +per-environment `env` map is stored in plaintext, so use deployment environment +variables under **Settings > Environments > Deployment Environment Variables** +for secret values. + +See [Keep definitions in source control](/environments/definition#keep-definitions-in-source-control) +for the Compose mount pattern and deployment workflow. ## Make verification possible diff --git a/apps/docs/environments/definition.mdx b/apps/docs/environments/definition.mdx index 9df82f8d7..4190c59c0 100644 --- a/apps/docs/environments/definition.mdx +++ b/apps/docs/environments/definition.mdx @@ -31,6 +31,64 @@ The definition is declarative and reproducible: the same YAML produces the same workspace shape for every task, and it is easy to review in a pull request or regenerate from scratch. +## Keep definitions in source control + +Self-hosted deployments can check environment definitions into git alongside +their deployment configuration. This gives environment changes the same review +and rollback workflow as application infrastructure. + +A typical repository layout is: + +```text +.roomote/ + environments/ + web.yaml + api.yaml +docker-compose.override.yml +``` + +To apply the checked-in files, mount the directory read-only into the Roomote +API container and point `ROOMOTE_ENVIRONMENTS_DIR` at the mounted path: + +```yaml +services: + api: + environment: + ROOMOTE_ENVIRONMENTS_DIR: /roomote/environments + volumes: + - ./.roomote/environments:/roomote/environments:ro +``` + +Commit the definition and Compose override, deploy that revision, and recreate +the API container so the new mount is attached. On later definition-only +changes, restart the API. At startup, Roomote reads every `*.yaml`, `*.yml`, and +`*.json` file in the directory. It creates missing environments and updates +existing ones by `name`. Repositories in a definition must already be linked to +the deployment; otherwise Roomote skips that definition and reports the reason +in the API logs. + +The files remain authoritative: edits made in the UI are recorded in version +history but are overwritten the next time the API starts. Removing a definition +does not delete its environment. It removes the managed marker and returns the +environment to normal manual management. + + + Do not commit secrets in an environment definition. Values under `env`, + command `env`, MCP server headers, and similar fields are stored as part of + the definition. Add sensitive values under **Settings > Environments > + Deployment Environment Variables** instead. + + +After deployment, open **Settings > Environments** and confirm that each +environment has the **Managed from file** badge. API startup logs also report +which definitions were created, updated, unchanged, or skipped. + +Roomote does not clone or poll a separate configuration repository. The +deployment must check out the files and mount them, or supply their contents +through `ROOMOTE_ENVIRONMENTS_YAML`. See [Environments](/environments#provision-environments-declaratively) +for reconciliation behavior and [Self-hosting](/self-hosting) for deployment +options. + ## Relationship to Dev Containers If you have used [Dev Containers](https://containers.dev), the environment From ab1a0bd6529fb8d0cbae50ef8428d33918d94f46 Mon Sep 17 00:00:00 2001 From: Matt Rubens <2600+mrubens@users.noreply.github.com> Date: Sat, 8 Aug 2026 00:01:00 +0000 Subject: [PATCH 2/2] docs: clarify hosted environment YAML workflow --- apps/docs/environments/definition.mdx | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/apps/docs/environments/definition.mdx b/apps/docs/environments/definition.mdx index 4190c59c0..e2d15cc17 100644 --- a/apps/docs/environments/definition.mdx +++ b/apps/docs/environments/definition.mdx @@ -33,9 +33,11 @@ regenerate from scratch. ## Keep definitions in source control -Self-hosted deployments can check environment definitions into git alongside -their deployment configuration. This gives environment changes the same review -and rollback workflow as application infrastructure. +Environment definitions are plain YAML, so any team can store them in a git +repository and review changes through pull requests. On Roomote Cloud, apply a +reviewed change by pasting the file into the environment editor's **YAML** view. +Applying the change is manual: Roomote Cloud does not read or sync environment +files from your repository. A typical repository layout is: @@ -47,8 +49,11 @@ A typical repository layout is: docker-compose.override.yml ``` -To apply the checked-in files, mount the directory read-only into the Roomote -API container and point `ROOMOTE_ENVIRONMENTS_DIR` at the mounted path: +### Self-hosted only: automatic file-based reconciliation + +Self-hosted deployments can apply checked-in files automatically at API +startup. Mount the directory read-only into the Roomote API container and point +`ROOMOTE_ENVIRONMENTS_DIR` at the mounted path: ```yaml services: @@ -83,10 +88,11 @@ After deployment, open **Settings > Environments** and confirm that each environment has the **Managed from file** badge. API startup logs also report which definitions were created, updated, unchanged, or skipped. -Roomote does not clone or poll a separate configuration repository. The -deployment must check out the files and mount them, or supply their contents -through `ROOMOTE_ENVIRONMENTS_YAML`. See [Environments](/environments#provision-environments-declaratively) -for reconciliation behavior and [Self-hosting](/self-hosting) for deployment +The startup provisioning mechanism does not clone or poll a separate +configuration repository. A self-hosted deployment must check out the files and +mount them, or supply their contents through `ROOMOTE_ENVIRONMENTS_YAML`. See +[Environments](/environments#provision-environments-declaratively) for +reconciliation behavior and [Self-hosting](/self-hosting) for deployment options. ## Relationship to Dev Containers