Commits

To version the content changes you make in your environments, Knock uses a commit model.

When you make a change to a content resource (like a workflow or a layout) in the Knock dashboard, you need to commit it to your current environment before those changes will appear in workflows triggered via the API.

Commits can be promoted to higher environments, such as production, and they can also be rolled back to prior commits. Lastly, commits provide a comprehensive version history for all content resources in your account.

A few additional notes:

• A commit is not a save. When you're drafting a workflow or a template, you can save and test your changes. Saved changes apply when you're using the test runner, but they do not apply to workflow runs or guide renders that are invoked via the API. To test changes via the API, you must commit them.
• "Publish" in production = commit to production. If you're working directly in production, the "Publish" button is the same as the "Commit" button. You'll still get a commit history and be able to roll back to prior versions if needed.
• Account-level resources are not version controlled. 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.
• You can commit changes using our CLI and management API. We offer both a Management API and a command line interface for interacting with Knock resources programmatically, both of which support programmatic commits.

An empty commit lets you commit (publish) a versioned resource without changing its content, similar to git commit --allow-empty. Empty commits are useful when you need to promote a resource to another environment, but the resource has no unpublished changes in the current environment.

Knock tracks promotable changes by comparing each resource's identifier (ref) and version (version_id). If a resource already points to the published version (current_version_id == published_version_id), a standard commit does not create a new promotable change. An empty commit solves this by creating a new version with the same content, then publishing that version, giving Knock a new version_id to include in promotion diffs, so you can promote the commit downstream even though the resource content has not changed.

What happens when you create an empty commit depends on the resource's current state:

• The resource has unpublished changes. The empty-clone step is skipped, and a normal publish happens instead.
• The resource is already published with no changes. An empty commit creates a new version with identical content.

Commit log entries for empty commits include audit metadata with empty: true and an optional message.

You can create empty commits using the CLI or the Management API. The bulk commit endpoint (PUT /v1/commits) supports the following resource types:

• workflow
• email_layout
• partial
• translation
• message_type
• guide
• audience

For translations, the resource_id can be a locale (es), a locale and namespace (es/courses), or a locale, namespace, and tenant (es/courses~tenant).

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.

If you're working in a non-production environment such as development, you can promote your changes to the production environment when you're ready to go live.

You can promote your commits from a given resource's page. You can also view all commits in one place in the Commits page, where you can promote individual or multiple commits at once.

Learn more about promoting commits in our environments documentation.

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.