Environments

Your Knock account starts with a single environment: production. Enabling environments adds a development environment where you can build and test changes before you promote them to production. After that, you can create additional environments (for example, a staging environment to mirror your own development lifecycle.) For an introduction to environments and when to use them, see the version control overview.

Each Knock environment has its own isolated data (such as users, tenants, and objects) and its own version-controlled content (such as workflows, guides, and layouts.)

Each environment has a set of data resources that are per-environment and will never be shared between environments. These data resources are not version-controlled.

An example: the users you identify in Knock. Your real production users are identified in your production environment, while your test development users are identified in your development environment.

Each environment has its own set of API keys which you use to send data to the environment. You can find your environment-specific API keys under "Platform" > "API keys" in the Knock dashboard.

Each environment has a set of content resources that are managed via version control. These are resources associated with the creation and orchestration of the content you send to your customers.

Here's how content resources work:

• Content can be created in any environment.
• Content can be promoted upwards through environments.
• Content can only be edited in the environment in which it was created.
• Content is versioned with commits. You can roll back to earlier commits at any time.

These rules enable two ways of working with content and shipping it to your end users in production. Every account can create content directly in production. Once you've enabled environments, you can also create content in development and promote it.

Enabling environments adds a development environment below production, and turns on promotion, additional environments, and branches. To decide whether your team needs them, see this frequently asked question.

Enabling environments requires the owner or admin role, or a custom role with environment management permissions. You can't turn environments off after you enable them.

• Your Development environment starts fresh. Knock copies your default email layout into development and nothing else. Your workflows, guides, and other content stay in production. This is expected: development is a new place to build, not a copy of production. You can clone individual resources into development from the dashboard, or use the CLI or Management API to pull production resources and push them to development in bulk.
• Existing content stays editable only in production. Content can only be edited in the environment where it was created, so resources you built in production stay there. To work on one in development and promote it, clone it into development with the same key.
• Development becomes your default environment. The Knock CLI and Management API target your account's default environment when you don't specify one. Before you enable environments, that's production. After, it's development, so pass production explicitly in any scripts that should keep targeting it.
• Members gain access to development. Account seats with the member role can work in any environment. To keep a team member limited to production, assign them the Production-only member role. Learn more in roles and permissions.
• Environment permission settings appear. The Modify resources in any environment and Promote resources settings appear on the Permissions page in your account settings.

Once you've enabled environments, the Modify resources in any environment setting on the Permissions page controls whether members can create and edit content directly in environments other than development. This setting is enabled by default.

1. Enabled. Members can create and edit content in any environment, including production.
2. Disabled. Every environment other than development is read-only. Members create content in development and promote it to production.

The Promote resources setting on the same page controls who can promote changes between environments. When it's disabled, only account seats with the owner and admin roles can promote.

You can clone supported resources from one environment to another in the Knock dashboard. Cloning creates a new copy of the resource in the destination environment. The clone gets a new key by default (with a -copy suffix) and is independent from the original.

Open a resource's action menu and select Clone (or Duplicate for email layouts) to start a clone. When your account has more than one writable destination environment, you can choose which environment to clone into.

For most resources, cloning is a dashboard-only feature and is not available through the Knock CLI or Management API. Goals are the exception: you can also clone them with the Management API or with knock goal clone.

You can clone the following resources across environments:

• Workflows
• Broadcasts
• Guides
• Message types
• Email layouts
• Audiences
• Goals
• Partials
• Translations
• Reusable requests
• Source event mappings

Archived resources cannot be cloned.

Clone and promote solve different problems:

1. Clone. Creates a new resource in another environment. Use this when you want a copy to exist in both environments, or when you need to copy content to an environment lower in the promotion chain (for example, from production to development).
2. Promote. Moves committed changes for an existing resource up through your environment chain, keeping the same key. Use this when you are following the development-to-production workflow and want the same resource to exist across environments.

When you clone a workflow, Knock also copies its channel step templates and workflow schema into the destination environment.

Which environments you can clone into depends on the modify resources in any environment account setting, following the same rules as creating and editing content:

1. Enabled. You can clone into any environment in your account.
2. Disabled. You can only clone into your development environment.

Branch environments cannot be used as clone targets.

1. Copy a broadcast from development to production. Create and test a broadcast in development, then clone it to production when you are ready to send it to real users.
2. Copy production content back to development. If you created a workflow directly in production and want to edit it using the promotion model, clone it into your development environment. You can give the clone the same key as the production resource if you plan to promote it back and overwrite the production version later.
3. Duplicate a workflow for experimentation. Clone a workflow within the same environment (or into another environment) to try changes without affecting the original.

Once you've enabled environments, your account has development and production environments. If you need an additional environment in Knock to mirror your own development lifecycle (for example, a staging environment), you can add it on the settings page of the Knock dashboard.

To create a new environment, go to the Environments page under the Version control section of your account settings. You'll see a button to "Create environment."

Environments are ordered, and that order determines your promotion path. When you create an environment, the Insert after select in the create modal determines where it lands. Choose the environment that the new environment should come directly after, and Knock inserts it one "level" above that environment.

Two constraints apply to the position you choose:

• You cannot insert an environment above production. Production is always the highest environment, so it isn't available in the select.
• You cannot insert an environment below development. Development is always the lowest environment, so the new environment will always sit above it.

By default the select is set to the second-to-last environment, which places the new environment directly below production. When your account has only development and production, that means a new environment is inserted between the two.

Environments cannot be re-ordered after they're created, as this would break the promotion model for previously-promoted changes.

A new environment is not empty. Knock seeds it from the environment directly below it when you create it, and different parts of your account are seeded in different ways:

Resource	What the new environment starts with
Workflows, guides, layouts, partials, translations, and reusable requests	Promoted from the environment directly below it (the latest committed version of each item; archived items are skipped).
Environment variable values	Empty. Values are per-environment and you need to set them.
Channel settings	Provider credentials are not copied and you need to configure them.
Source settings	Every source in your project appears in the new environment with default settings and its own newly generated source URL. No settings are copied, so you need to point your provider at the new environment's URL.
Hosted preference center configuration	The default configuration.
API keys	A new public and secret key pair.
Users, tenants, objects, messages, and logs	Nothing. Data is never copied between environments.

You can rename any additional environment that you created. Your Development and Production environments cannot be renamed.

A renamed environment keeps its unique ID, its API keys, and its position in your promotion path. Workflows, guides, layouts, and other content are untouched, and no data moves between environments. Any environment-specific custom permissions are also preserved on the renamed environment.

Renaming an environment requires the owner or admin role, or a custom role with environment management permissions.

We recognize the importance of protecting your sensitive data, so we designed Knock from the ground-up with privacy and security in mind.

There are two tools you can use to control access to your data in the Knock dashboard:

• Roles and permissions. Knock offers built-in roles for common team functions, and on Enterprise plans custom permission groups with per-environment access controls. For example, you can give support team members access to debug issues without permission to change notification logic, or deny access to an environment entirely.
• Customer data obfuscation. Use environment-level controls to hide customer data for every team member in an environment. On Enterprise plans, custom permission groups can also set per-environment obfuscation rules.