> ## Documentation Index
> Fetch the complete documentation index at: https://docs.observal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete-folder skill rollout (operators)

`registry.skill_folder_delivery_enabled` is a **deployment-level rollout control**, not a permission that authors request for every skill. After a verified rollout it should remain enabled for normal operation: authors save drafts, explicitly submit exact revisions, reviewers inspect those revisions, and consumers install approved versions. The default is **off** because enabling it while older API/worker processes or clients are still running can allow reviews that some installations cannot safely deliver. Do not change the default just to make a test pass.

## Before enabling

* Obtain an independently reviewed release and explicit operator authorization. The PR being green, a fresh database, and a browser demonstration do not substitute for this decision.
* Back up the existing PostgreSQL database; rehearse restoring **representative historical data** into a disposable database and upgrading it through the current Alembic head. Check ownership, version pointers, private review provenance, and file hashes before and after. Never trial migrations on the live database first. Apply PostgreSQL and ClickHouse migrations in the normal deployment sequence.
* Serve the browser over HTTPS (localhost is exempt). Browser folder editing and binary downloads verify SHA-256 with Web Crypto and fail closed on insecure LAN HTTP origins rather than returning unverified bytes.
* Schedule a maintenance window: turn the gate off, then drain and stop *every* old API and worker process **before running the new init container or Alembic upgrade**, not merely before enabling delivery. A normal `make rebuild` or `docker compose up` may run migrations while old services are still serving; neither Compose dependencies nor an off gate serialize schema changes with old processes. Keep the old processes stopped if initialization fails. After the migration succeeds, start only compatible server, worker and web images. Once the new API is healthy, restart `observal-lb` so nginx resolves the recreated API and web containers; an old load balancer can return 502 even when both new containers are healthy. Verify the Alembic revision and health **through the public load balancer**, and confirm its public config endpoint reports the gate off. For archive-based installs that preserve `.env`, the installer only stages the package: follow the [package cutover commands](/self-hosting/upgrades#server-package-upgrades), including selecting/pulling the new image tag, before checking health. Do not enable delivery while any old process is running.
* Distribute a CLI that understands integrity-checked exact-version folder bundles, managed receipts, backups and recovery. Use HTTPS to the trusted server in production: SHA-256 hashes from that same server are not a cryptographic signature and cannot authenticate an untrusted connection. Localhost HTTP is only for isolated testing. Instruct users not to run an older CLI against a managed folder. Check all advertised skill-capable harnesses and both user/project scopes on a disposable instance.
* Rehearse a separate end-to-end author → exact draft → submit → review → approved install → checked upgrade → backup restore journey on a disposable instance, including refusal to overwrite local edits and failed delivery. Review the Git/historical conversion, pinned-Agent and delegation paths separately. Preserve existing `git_fetch` and resource-less direct behavior.
* If any of these checks are incomplete, leave the gate **off**, and tell authors they can only save drafts for later review. An off gate is a staging state, not an acceptable permanent developer experience for complete folders.

## Enable after the fleet is homogeneous

An administrator can change **Registry → Skill folder delivery enabled** under the server's Admin Settings (the setting is stored in the DB, not an `OTEL_*` environment variable). Record the approver, deployment/client versions, migration rehearsal, and time of activation. After enabling, confirm `/api/v1/config/public` reports `skill_folder_delivery_enabled: true`; then submit a disposable draft, approve the exact candidate and verify an isolated CLI installation. Leave the gate on for normal use once these checks pass. New drafts still require an explicit submission; saving never submits or automatically approves anything.

## If the rollout fails

Set the gate **off** to stop *new* complete-folder submissions and delivery while investigating. This does **not** roll back migrations, undo an existing approval, remove installed files or restore an older database. Retain receipts and backups, preserve the approved release bytes and investigate affected clients before retrying. Never reintroduce an old worker while reviews created under the new rules remain eligible. A database restore, historical downgrade or client rollback needs its own separately rehearsed recovery procedure; disabling the gate alone is not that procedure.

See [the developer workflow](/skill-folder-workflow) for the user-facing lifecycle and [self-hosting upgrades](/self-hosting/upgrades) for the general deployment order.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.