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.

Every promote gets a promote_group_id. Knock stamps the ID on each commit the promote creates in the destination environment, so you can group the commits that moved together. Promote endpoints and commits return the ID:

• The promote all and promote one endpoints return a promote_group object with the ID, the source and destination environments, and the number of commits the promote created. The object is null when a promote all has nothing to promote.
• The promote_group_id field on a commit identifies the promote that created it, and promoted_from_commit_id points to the commit it was copied from. Both are null on commits that weren't created by a promote.

To list the commits a promote created, pass promote_group_id to the list commits endpoint. The endpoint also accepts promoted_from_environment, since, and until filters.

Use the commits.promoted webhook event to trigger work in your own systems when a promote lands in an environment, such as running smoke tests or notifying your team. Knock sends one event for each promote, to webhooks in the destination environment, with the promote group ID as data.id, the source and destination, the user who promoted, and the number of commits the promote created.

A few things to know:

• Promotes don't send *.committed events. Events like workflow.committed fire when you commit a change in an environment. The commits a promote copies into the destination don't fire them, so subscribe to commits.promoted instead.
• Use the promote group ID to deduplicate. Webhook deliveries can be retried, so use the ID to make sure your handler processes each promote once.
• Each environment hop is its own promote. When a promote moves commits across more than one environment, each hop sends its own event with its own promote_group_id.

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.