> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/operations/devops/version-sets-best-practices.md). # Version Sets & Promotion Version sets define which agent, state machine, and model preferences a service uses. They let you iterate safely, like Git branches, while keeping production stable. * **Purpose**: pin exact versions for a service run (agent, state machine, LLM model preferences). * **Analogy**: treat version sets like Git branches for your service configuration. Every service carries two special sets, `edge` and `release`, with platform-enforced guardrails: {% hint style="warning" %} Guardrails * `edge` cannot be updated or deleted. * `release` cannot be deleted and is the default when no version set is specified. * Custom version sets cannot be deleted if they're referenced by simulation unit tests. {% endhint %} ## What Each Special Set Means * `edge` (locked default settings) * Always the latest agent and state machine, with no explicit LLM preferences. * Cannot be updated via the upsert API and cannot be deleted. * Use it for quick local validation or smoke checks, not for stable user exposure. * `release` (default exposed to users) * Used by conversations and real-time APIs when `service_version_set_name` is not provided. * Cannot be deleted, but can be updated to promote a tested configuration to production. ## Creating and Updating Version Sets * **Create/Update**: use the Service Version Set upsert API to create named sets (for example, `personal-alex`, `test`, `preview`). All sets except `edge` are updatable. * **Delete**: allowed for custom sets, but not for `edge` or `release`. Deletion is blocked if a set is referenced by any simulation unit tests. * **Permissions**: * Create: `Service:CreateVersionSet` * Update: `Service:UpdateVersionSet` * Delete: `Service:DeleteVersionSet` ## How Version Sets Are Used at Runtime * Conversation APIs default to `release` if `service_version_set_name` is omitted. * Simulation unit tests and test runs must explicitly specify the target version set. * Services are created with both `edge` and `release` by default. `release` equals `edge` unless you specify otherwise at creation time. ## Recommended Workflow (Git-Branch Style) 1. **Personal branch** * Create a personal version set (for example, `personal-yourname`) with `forge version-set upsert personal-yourname -s MyService -e --latest --apply`, pin agent and state machine versions, and set LLM preferences. * Iterate locally and validate via small, focused simulation unit tests. 2. **Merge into `test`** * Upsert the shared `test` version set with your candidate configuration (`--copy-from personal-yourname`). * Run your simulation unit test set on `test`. Fix regressions here. 3. **Promote to `preview`** * Copy the `test` configuration into `preview` with `forge version-set upsert preview -s MyService -e --copy-from test --apply`. * Run the full simulation suite on `preview` and conduct stakeholder UAT. 4. **Release** * If `preview` passes full sims and UAT, promote with `forge version-set promote preview release -s MyService -e --apply`, which auto-creates a `release-previous` backup for one-command rollback. * Don't delete `release` or `edge`. Use them as stable anchors. ### Promotion Flow ```mermaid --- config: gitGraph: mainBranchName: 'release' showCommitLabel: true rotateCommitLabel: true --- gitGraph commit id: "Initial" tag: "v1.0.0" %% First development cycle branch personal-dev commit id: "Agent v2" commit id: "LLM: standard" commit id: "State: v3" checkout release branch test checkout personal-dev commit id: "Agent v2" checkout test commit id: "Test passed ✓" checkout release branch preview checkout test commit id: "Test passed ✓" checkout preview commit id: "UAT ✓" type: HIGHLIGHT checkout release merge preview id: "Promote" tag: "v1.1.0" type: HIGHLIGHT %% Second development cycle checkout release commit id: "Stable" branch personal-dev-2 commit id: "Agent v3" checkout release branch edge commit id: "Auto-latest" type: REVERSE tag: "🔒 Locked" ``` ## CLI Reference The Agent Forge CLI covers the full version-set lifecycle from the terminal: listing and inspecting sets, upserting with pinned or copied configurations, diffing, promoting with auto-backup, rolling back, and discovering services and asset versions. All mutating commands are dry-run by default and run pre-flight validation. {% content-ref url="/pages/oCVN8zs4FK3j2WwtKtbt" %} [Version Set CLI Reference](/developer-guide/operations/devops/version-sets-best-practices/version-set-cli.md) {% endcontent-ref %} Validation rules for channels, presets, and LLM preferences are driven by service tags. See [Channel Tagging: Validation](/developer-guide/operations/devops/channel-tagging.md#validation) for the canonical rules table. ## Practical Tips ### Naming Conventions * Names may contain letters, digits, `-`, and `_` only, with a maximum length of 40 characters. * Prefer lowercase for readability and consistency. * Examples: `personal-alex`, `test`, `preview`, `release`. ### Operating Tips * **Drift control**: treat `release` as immutable except during deliberate promotion. Keep a changelog of which version set was promoted, when, and by whom. * **Deprecate rather than delete**: the platform blocks deletion of sets referenced by simulations. When many artifacts depend on a set, prefer deprecation and migration over deletion. * **Fast rollback**: use `forge version-set rollback` to quickly revert to the previous release configuration. The `release-previous` backup is created automatically when promoting to `release`. * **Observability**: compare simulation metrics between `test`, `preview`, and `release` to quantify impact before promotion. ## API Touchpoints ### API References {% openapi src="" path="/v1/{organization}/service/" method="post" %} {% endopenapi %} {% openapi src="" path="/v1/{organization}/service/{service\_id}/version\_sets/{version\_set\_name}/" method="put" %} {% endopenapi %} {% openapi src="" path="/v1/{organization}/service/{service\_id}/version\_sets/{version\_set\_name}/" method="delete" %} {% endopenapi %} These endpoints enforce the guardrails described above: service creation initializes both special sets, the upsert API accepts `release` and custom sets, and the delete API rejects the protected and simulation-referenced sets. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/operations/devops/version-sets-best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.