Migrating your enterprise

Progressive rollout of declarative environment configuration across your enterprise: rollout states, per-org overrides, phased migration playbook, and monitoring.

Migrating an enterprise from classic environment setup to declarative configuration is a significant change. The Rollout page gives enterprise admins granular control over this transition. You can enable blueprints for a few pilot orgs, expand at your own pace, and roll back instantly if something goes wrong.

Enterprise rollout states

The Rollout page presents a Rollout mode selector that controls how blueprints are available to organizations. There are three modes, plus an initial state before declarative environments are activated:

State	What it means	Effect on organizations
Not enabled	Declarative environments haven’t been activated for the enterprise yet	No orgs see the environment pages. All orgs use classic setup. Contact your Cognition administrator to enable.
Testing	Only manually enabled organizations use declarative environments	Enterprise admin opts individual orgs in from the Rollout page. All other orgs remain on classic setup and see no changes.
Available	Org admins see a migration prompt and can switch on their own	Org admins on classic setup see a migration callout on their Machine Configuration page. They can self-service migrate without enterprise admin intervention.
Enabled by default	New organizations default to declarative environments	All new orgs start on blueprints. Existing orgs that were on classic setup with repos receive automatic classic overrides.

The progression is: Testing → Available → Enabled by default. You can move between Testing and Available freely using the Rollout mode dropdown. However, Enabled by default is a permanent action that cannot be undone without a Cognition administrator.

Enabled by default is permanent. Once you activate this mode, it cannot be reverted to Testing or Available without contacting your Cognition administrator. Make sure your enterprise blueprint is fully validated and most orgs are on blueprints before enabling this mode.

Testing mode details

In Testing mode, organizations that haven’t been opted in continue to use classic setup and see no changes to their experience. The enterprise admin can opt individual orgs in from the Rollout page. Only those orgs switch to declarative configuration. This is the baseline mode when declarative environments are first activated for an enterprise.

Available mode details

Available mode adds a migration nudge: org admins who are still on classic setup see a callout on their Machine Configuration page encouraging them to migrate to declarative configuration. This doesn’t change their setup or give them access to the full environment configuration pages. It simply makes them aware that blueprints are available and provides a self-service path to opt in. This is useful for building awareness and letting org admins migrate at their own pace.

Per-org overrides

Enterprise admins can override the rollout state for individual organizations directly in the per-org table on the Rollout page:

• In Testing or Available mode: Opt specific orgs in to blueprints. These orgs switch from classic setup to declarative configuration immediately.
• In Enabled by default mode: Opt specific orgs out back to classic setup. These orgs continue using their classic configuration.

Overrides are persistent. They survive mode changes. If you opt an org into blueprints during Testing mode, it stays on blueprints when you transition to Available or Enabled by default.

Automatic classic overrides

When activating Enabled by default, a safety mechanism prevents disruption: any org that is currently on classic setup and has repositories configured automatically receives an explicit classic override. This means the transition doesn’t change anything for orgs that are actively using classic setup. They continue as-is until you explicitly migrate them.

Orgs without repositories (or orgs already on blueprints) are unaffected by this guard.

Recommended migration playbook

The best approach is to build and validate your configuration in isolation before opening it up to org admins. Don’t do a big-bang migration. Start controlled, verify, then expand.

Phase 1: Build and verify in isolation (Testing)

Start with the enterprise in Testing mode. Orgs cannot opt in on their own, so you have full control.

1. Activate declarative environments for the enterprise. Your Cognition administrator enables the feature, which puts the enterprise into Testing mode.
2. Create a dedicated test org for environment configuration testing. This org exists solely for validating your blueprints.
3. Enable declarative configuration for this test org only (via per-org override on the Rollout page).
4. Configure your enterprise blueprint: install all shared language runtimes, security tools, corporate certificates, internal CLIs, proxy settings, and registry auth. This is your base layer that every org will inherit.
5. Configure an org blueprint for the test org with any org-level tools or registry config.
6. Add repository blueprints for a representative set of repositories. Pick repos that cover your most common tech stacks.
7. Verify end-to-end: start Devin sessions on these repos and confirm everything works. Repos should be cloned, dependencies installed, lint/test/build commands running correctly, and all tools at expected versions.

Don’t just check that builds succeed. A green build doesn’t always mean a working environment. A missing PATH entry, wrong tool version, or missing registry auth can slip through. Always verify by running a real Devin session.

Phase 2: Enable opt-in for org admins (Available)

Once you’ve confirmed that your enterprise → org → repo blueprint stack composes correctly and produces working environments:

1. Communicate internally to org admins that declarative configuration is available and ready.
2. Switch to Available mode: change the Rollout mode dropdown from Testing to Available. Org admins on classic setup now see a migration callout encouraging them to migrate.
3. Org admins can now migrate their own organizations. Because the enterprise blueprint already provides the base layer (runtimes, tools, certs, registries), org admins only need to configure what’s specific to their team and repos.

Each org admin can use the migration assistant to make this easy. Devin can inspect the org’s existing snapshot and automatically generate equivalent blueprint configuration. See Migrating to declarative configuration for the step-by-step flow.

Build a library of template blueprints for your most common tech stacks (Node.js, Python, Java, Go, multi-language monorepos) and share them internally so org admins don’t start from scratch. The Template library is a good foundation.

Phase 3: Expand and clean up (Enabled by default)

1. Activate Enabled by default when most orgs are on blueprints. This is a permanent action — orgs that were on classic setup with repos get automatic classic overrides, so nothing changes for them.
2. New orgs created after this point start on blueprints by default.
3. Monitor the Rollout page for build health across all orgs. Filter by “Classic” to see who hasn’t migrated yet.
4. Work with remaining org admins to migrate stragglers. The migration assistant makes this straightforward.
5. Remove classic overrides once all orgs are verified on blueprints.

Classic configuration is always preserved. Nothing is deleted when an org switches to blueprints. If something goes wrong, enterprise admins can switch any org back to classic setup from the Rollout page using per-org overrides.

Accelerated migration strategy

For enterprises that want to move quickly, here’s an approach that minimizes the per-org migration burden:

1. Start in Testing mode (so each org can be opted in individually).
2. Configure the enterprise blueprint first. Get admins to set up the enterprise blueprint with shared runtimes, tools, certificates, and registry configuration. This is the base layer that all orgs will inherit.
3. Switch to Available mode. This enables the migration nudge so org admins see a callout on their Machine Configuration page and can self-service migrate.
4. Blast documentation through whatever internal channels exist (Slack, email, wiki) and encourage org admins to opt in on their own. The migration assistant makes this self-service for org admins.
5. Auto-enable for orgs with 0 repositories currently configured. These orgs have nothing to migrate — there’s no risk in switching them to blueprints since they don’t have an existing classic setup to preserve.
6. Progressively migrate remaining orgs one by one. With the enterprise blueprint already configured, each org migration only needs to add org-specific and repo-specific configuration on top. This is much simpler than migrating from scratch.
7. Activate Enabled by default once most orgs are migrated. New organizations created after this point start with blueprints enabled.

This approach frontloads the enterprise blueprint configuration (the highest-leverage work) and then lets individual orgs migrate at their own pace with minimal effort.

Rolling back

Things don’t always go smoothly. The rollout system supports rollback at every level.

Per-org rollback

Enterprise admins can toggle any individual org back to classic setup from the Rollout page:

• The org immediately reverts to using its classic setup snapshot.
• Classic configuration is preserved. Nothing is lost when an org switches to blueprints, so switching back is safe.
• Active sessions are not affected. The change takes effect on the next session.

Mode rollback

Enterprise admins can switch between Testing and Available freely using the Rollout mode dropdown. This is useful if you want to pause self-service migration while you investigate an issue.

Enabled by default cannot be reverted by the enterprise admin. If you need to revert from Enabled by default, contact your Cognition administrator. Per-org overrides can still be used to switch individual orgs back to classic setup at any time.

Rollback doesn’t delete blueprints or classic configurations. Both are preserved regardless of which mode is active, so you can switch back and forth between Testing and Available without losing work.

Monitoring rollout health

The Rollout page provides a dashboard for tracking migration progress across your enterprise.

KPI row

At the top of the page, summary metrics give you a quick read on rollout status:

• Blueprint orgs: Number of organizations currently on blueprints
• Rollout percentage: Percentage of orgs on blueprints out of the total
• Build health: Aggregate build status across blueprint orgs

Per-org table

Below the KPIs, a detailed table shows every organization:

Column	Description
Organization	Org name
State	Current mode: Blueprints or Classic
Override	Whether the org’s state is an explicit override vs. enterprise default
Classic repos	Number of repos with classic setup configuration
Blueprint repos	Number of repos with blueprints
Latest build	Status of the most recent build (Success, Partial, Failed, etc.)

Filtering

Filter the table by:

• All: Every org in the enterprise
• Blueprints: Orgs currently on blueprints
• Classic: Orgs currently on classic setup
• Overrides: Orgs with explicit state overrides (either direction)

Concurrency safety

State transitions are protected against simultaneous changes. If another admin changes the enterprise state between when you loaded the page and when you submit your change, the request is rejected with a conflict error.

This prevents accidental overwrites when multiple enterprise admins act at the same time. If your change is rejected, refresh the page to see the current state and resubmit if still appropriate.

Audit logging

All rollout state transitions are recorded in audit logs:

• Enterprise mode changes (Testing → Available, activation of Enabled by default, etc.)
• Per-org override changes (org opted in, org opted out, override removed)
• Which admin made the change and when

These logs are available through your enterprise’s standard audit log interface.