Commits

To version the changes you make in your environments, Knock uses a commit model. When you make a change to a workflow or a layout in the Knock dashboard, you'll need to commit it to your development environment before those changes will appear in workflows triggered via the API. By default, changes must be made in development and promoted to production. If you've enabled production write access, resources can also be edited directly in production.

After you modify a resource, you'll see a "Save" button that allows you to store those changes. When you're ready to permanently store your updates with version control, they should be committed with the "Commit to development" button that will come into focus after changes have been saved.

A few things to note:

• Channel configurations, branding, and variables do not need to be committed, as they live at the account-level. This means that if you make a change to a channel configuration, it will update immediately on notifications sent in that environment.
• Any changes you have saved but not yet committed will apply when you're using the test runner. This allows you to test your latest changes before you commit them to your development environment.
• You can work with Knock resources outside of your dashboard if you prefer. We offer both a Management API and a command line interface for interacting with Knock resources programmatically. The commit model applies to all methods of interacting with Knock resources, whether directly in the dashboard or with the Management API or CLI.

Clicking the "Commit to development" button will show you a view of changes between your current commit and the most recent version of the resource that you're updating. Commit diffs are also available on your full commit log (viewable on the "Commits" page in your dashboard), so you can view the commit history for a resource and know exactly what was changed with each commit.

Knock is designed to allow large teams to create and manage notifications at scale. That means that changes must be versioned, tested, and promoted to production environments, so that if there are any issues they can be rolled back with ease.

Knock uses a model where all changes to the production environment must be promoted and cannot be made directly. Changes must be made in the development environment, then staged and tested before being rolled out (similar to a git-based workflow).

To promote a committed change to a higher environment, navigate to the Commits page in your Knock dashboard sidebar and click on "Unpromoted changes." Here you'll see a list of commits that are ready for promotion. Clicking "View commit" on a given commit will show you a commit diff for that change, and clicking the "Promote to [environment]" button will promote the staged commit to the next-higher environment (whose name is displayed on the button).

A typical deployment lifecycle in Knock looks like:

1. Introduce any backend changes to support a new workflow (users and preference properties)
2. Build the workflow in a dev environment in Knock and commit it to that environment
3. Test the workflow
4. When you're ready to go live, promote the workflow to production

If you've made a change in a commit that you want to revert, you can use the "Revert commit" feature to "undo" that change. You can find the revert commit action on the Commits page in the dashboard, under the "Unpromoted changes" and "Commit log" tabs.

Reverting a commit will:

• Create a new commit with a message that indicates the commit reverts a preceding commit
• Wind back the state of the resource to the change that precedes the commit
• Undo any uncommitted changes on the resource

Because the revert will produce a new commit, you can then promote that commit to other environments to make that change live in those environments.

When production write access is enabled, Knock tracks the origin environment for each resource. A resource can only be edited in the environment where it was originally created. This protects version-controlled resources from unintended production edits while enabling direct production editing for resources created there.

Every workflow and guide has an origin environment that determines where it can be edited:

Development-originated resources

• Created in development environment
• Can be promoted to production (and other environments)
• Can only be edited in development
• Visible in production with a "Source: Development" indicator
• Attempting to edit in production shows message: "This resource was created in development and can only be edited there"

Production-originated resources

• Created directly in production environment
• Cannot be promoted to other environments
• Can only be edited in production
• Not visible in development or other environments
• Managed independently from version control workflow

When viewing a resource in an environment other than its origin, Knock shows visual indicators:

• Badge display. A "Source: [Environment]" badge appears at the top of the resource
• Edit restrictions. Clicking edit shows a helpful message directing you to the origin environment
• Origin environment link. The message includes a link to open the resource in its origin environment

Version-controlled transactional workflows

1. Engineer creates "password-reset" workflow in development
2. Tests it thoroughly in development environment
3. Promotes to production
4. Workflow remains editable only in development
5. Future edits follow: edit in dev → test → promote to production

Direct production content workflows

1. Marketer (Production Member role) creates "feature-announcement" guide in production
2. Edits content directly as needed
3. No promotion required or available
4. Changes go live immediately in production

Hybrid approach

Teams can use both models simultaneously:

• Engineers manage transactional workflows via promotion (dev → prod)
• Marketers manage in-app content directly in production
• Origin environment protection keeps them separate

To identify a resource's origin environment:

1. Open the resource in the Knock dashboard
2. Look for the "Source: [Environment]" badge at the top
3. If no badge appears, the resource was created in the current environment

Alternatively, when attempting to edit a promoted resource in a non-origin environment, you'll see a message indicating where the resource can be edited.

If you need to transition a workflow from one model to another:

1. Create a new workflow in the desired environment
2. Copy the configuration and templates from the original workflow
3. Test the new workflow
4. Archive the original workflow
5. Update your trigger calls to use the new workflow key