Adding Knock to your CI/CD pipeline

With the Knock CLI, you can add Knock directly into your existing CI/CD pipeline to automate how notification changes move through your Knock environments alongside your application code.

This tutorial walks through a GitHub Actions setup built around Knock branches, Knock's way of isolating in-progress changes. The workflow mirrors a standard development cycle:

1. A feature branch in Git maps to a Knock branch. When you push changes to .knock/, they sync automatically to the matching Knock branch.
2. When a pull request is merged, the Knock branch merges into your development environment and changes are promoted to staging.
3. When you're ready to ship, a production deploy promotes changes from staging to production in Knock.

This tutorial assumes you have installed the Knock CLI and have your Knock resources checked in to a .knock directory in your repository. It also assumes that you have created a "Staging" environment in Knock in addition to the Development and Production environments that are provided by default.

Use the knock pull command to download your current Knock resources from the dashboard and develop them locally.

When starting a new feature, create a matching Knock branch and switch to it:

As you make changes, push and commit them to your Knock branch:

The following workflows automate your Knock updates throughout the full development lifecycle: syncing changes as you push, merging and promoting when a PR lands, promoting to production on deploy, and cleaning up branches when they're removed.

Each GitHub Action below requires a KNOCK_SERVICE_TOKEN secret. You can generate a service token in the Knock dashboard under Settings > Service tokens. Add it to your GitHub repository under Settings > Secrets and variables > Actions.

This workflow runs whenever you push changes to a non-main branch that touch your .knock directory. It creates the matching Knock branch if it doesn't already exist, then pushes and commits your changes to it. The Git commit SHA is included in the Knock commit message, so you can correlate Knock commits back to your Git history using knock commit list.

This workflow runs when a pull request targeting main that includes changes to .knock is merged. It merges the corresponding Knock branch into your development environment, then promotes those changes to staging in the same job. Running both steps sequentially in a single workflow ensures your Knock resources reach staging along with your application deployment.

Once you've verified staging, promote your Knock changes to production. Tie this to whatever event represents a production deploy in your pipeline: a published release, a manual workflow dispatch, or a push to a release branch are all common choices. Using a deliberate trigger (rather than promoting automatically on PR merge) gives you a chance to verify staging before changes reach production.

This workflow deletes a Knock branch when its corresponding Git branch is removed, keeping your Knock account in sync with your repository.

The standard Git revert flow works naturally with the branch-based setup above. When a developer runs git revert and opens a pull request, the sync workflow pushes the reverted .knock/ state to a new Knock branch. Merging that PR triggers the merge-and-promote workflow, landing the corrected state in development and staging automatically.

For situations where something has already reached production and you need to recover before a revert PR can land, you can use Knock's revert feature directly in the dashboard from the Commits page, then promote the resulting commit through your environments. Alternatively, you can force-push a known good state from the command line using the Git SHA recorded in your Knock commit messages: