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 in the Knock dashboard, you save it as a draft. You need to commit the draft before it goes live in your environment and is used for notifications that are triggered via the API.

In your production environment, the dashboard labels this action as "Publish." Publishing is committing: each publish creates a commit in your commit log, and you can roll back to a prior version by reverting the commit if needed.

A few additional notes to keep in mind:

• 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 through the API. To test changes through the API, you must commit them.
• 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.

You can commit a resource from its page in the dashboard, or commit several at once from the Commits page. The Commits page lists your uncommitted changes, and "Commit all" commits every change on the list in one step.

When your account has environments enabled, you commit changes to the environment you're working in. A commit in development doesn't change production until you promote it.

When you commit or publish a change, Knock shows you a diff between your changes and the most recently committed version of the resource. Commit diffs are also available in your full commit log on the Commits page in your dashboard, so you can view the commit history for a resource and know exactly what changed with each commit.

Promotion applies to accounts with environments enabled. If your account has a single production environment, there's nothing to promote: publishing a change makes it live.

If you're working in a lower environment such as development, you can promote your commits to the next environment, up to production, when you're ready to go live.

Commits can be promoted directly from a given resource's page. You can also view all unpromoted commits in one place on the Commits tab, where you can promote individual changes or all unpromoted changes at once.

Learn more about how promotion moves content between environments 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 "Commit log" tab. If your account has environments enabled, it's also under the "Unpromoted changes" tab.

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 produces a new commit, it takes effect in the environment where you make it. If your account has environments enabled, promote the revert commit to make the change live in higher environments.

An empty commit lets you commit (publish) a versioned resource without changing its content, similar to git commit --allow-empty. If your account has environments enabled, 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 to the next environment 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).