Using ConfigCat for Staged Rollouts and Canary Releases

Using ConfigCat for Staged Rollouts and Canary Releases

A walk-through guide on how to effectively use ConfigCat for implementing Staged Rollouts and Canary Releases in software projects.

The primary goal of software developers is to ensure user satisfaction with the features or updates they introduce. However, achieving this goal can be challenging without the right release strategy. The question often asked, then, is, "How can developers be certain that a new update or feature delivers optimal results to end users?"

Two strategies that can be employed to address this concern are staged rollouts and canary releases. These strategies can be implemented using feature flags, and in this article, we explore how ConfigCat, a popular feature flag provider, can be used to perform staged rollouts and canary releases.

Using ConfigCat for staged rollouts and canary releases cover image

What are staged rollouts and canary releases

Staged rollouts and canary releases are both techniques used in software deployment, but they differ in their approach and purpose:

  • Staged Rollouts: In a staged rollout, the new feature or software update is gradually released to a larger percentage of users over time. It typically starts with a small group and increases in stages until all users have access to the update. This method is used to monitor its performance with users and gather iterative feedback while minimizing the impact of any potential bug or issues.

  • Canary Releases: Canary releases on the other hand involve deploying the new version or feature to a small subset of users initially, often chosen at random or based on specific criteria, before pushing them out to the entire user base. This group, referred to as the 'canary', acts as a test to gauge the new version's stability and performance. If no issues arise, the release is then rolled out to the entire user base. This approach is more focused on identifying and addressing issues before they affect all users.

In essence, while both strategies aim to mitigate risk by releasing software updates to a subset of users initially, staged rollouts do so in a more gradual, phased manner, whereas canary releases target a smaller, more specific group for initial testing. This ensures that the new changes introduced work as expected while minimizing any negative impact on the user experience.

Here is a diagram that illustrates a staged rollout and a canary release:

Diagram of staged rollouts and canary releases

The role of ConfigCat in staged rollouts and canary releases

ConfigCat is a feature flag management service that serves as a central dashboard to easily manage your feature flags and provides the essential tools needed to perform a staged rollout or canary release.

But how can these strategies be implemented and used? The simple answer is to use feature flags.

The first step is to create a feature flag for the new feature. Then, wrap the feature's code in a conditional if-statement that checks if the feature flag is enabled. This would allow the feature to be included in the app's code base, but until its flag is toggled on, it will be hidden from users.

Instead of showing the new feature to everyone when the flag is on, you can configure the flag to allow the adoption of either strategy. This is where the magic of ConfigCat comes in, specifically its user-targeting capabilities.

Performing a canary release with ConfigCat

To perform a canary release using ConfigCat, one can leverage its user-targeting abilities. Once the feature flag is created, user-targeting rules can be configured to target users based on their email, country, or any other custom attribute.

For instance, if a new feature should be rolled out to only users within a company, you can set an email target rule. In the ConfigCat dashboard, the CONTAINS operator can be used to target all email addresses that contain This will ensure that only users with email addresses containing will have access to the new feature. Here's how to do this:

  1. Create a new feature flag in the ConfigCat dashboard with the following details:
  • Name: Chat feature

  • Key: chatFeature

  • Description: A new chat feature for our mobile app

Adding a feature flag in ConfigCat dashboard

  1. Click the TARGET SPECIFIC USERS button and select Email as the comparison attribute to target. Then, select the CONTAINS comparator from the dropdown and enter as the comparison value. Here is what that looks like in the ConfigCat dashboard:

Now that the feature flag and targeting rule have been created, the next step is to integrate ConfigCat's SDK client for the appropriate coding language.

  1. The code snippet below shows how ConfigCat's JavaScript SDK can be used to check if the chat feature is enabled for a user. Start by installing the SDK:
npm i configcat-js
// Import the ConfigCat SDK
import * as configcat from "configcat-js";

// Initialize the SDK with your SDK key
const configCatClient = configcat.getClient("YOUR-CONFIGCAT-SDK-KEY");

// Define the user object
const user = {
  identifier: "f8c9c1a5-7d9c-4c7e-9e4c-9d3d2b5b3c5c",
  email: "",

// Get the value of the feature flag, while passing in the user object

const chatFeature = configCatClient.getValueAsync("chatFeature", false, user);

// Check if the chat feature is enabled
if (chatFeature) {
  // Show the chat feature
} else {
  // Hide the chat feature

Because the user Jane has an email address that contains, she will have access to the chat feature.

Scenarios can be different, and email is not the only way to target users. Users can also be targeted based on their country, or any other custom attribute. More information on how to do this can be found here.

Best practices for using ConfigCat for staged rollouts and canary releases

Rollouts and canary releases are great ways to test and evaluate new features and changes before making them live for the entire user base. To achieve the best results, a well-thought-out plan and design are required. Here are some general best practices to keep in mind when using ConfigCat for staged rollouts and canary releases:

  • Start small: When performing a staged rollout or canary release, it's best to start with a small subset of users. This will allow the new changes to be tested on just a few users before rolling it out to everyone. In addition to the example described above, ConfigCat also provides a percentage option for setting the percentage of users that should have access to the new feature. Here is an example of what that setting looks like:

Using percentage option in ConfigCat dashboard

  • Roll out gradually: Once the new changes are released to a small subset of users, continue rolling it out gradually if the feedback is satisfactory. This will allow the new changes to be evaluated by larger subsets of users before they become available to everyone. In the example provided, if the feedback is positive, you can add more targeting rules to the feature flag to make the chat feature available to more users.

  • Monitor and analyze: This will help provide valuable insights to determine if the new feature or update is working as expected. Using commercial tools like Amplitude and Datadog can aid in monitoring and analyzing the results of each rollout in real-time. Here are links to some blog articles that discuss this topic in more detail:

  • Have a recovery strategy: Even though the new changes are tested on a small subset of users, there is still a chance that they may not work as expected when the feature reaches more users. Having a recovery strategy in place is essential. It allows you to roll back the changes if they do not work as expected. With ConfigCat, performing a feature rollback is just a few clicks away, and the best part is that you can do this from the dashboard without ever needing to edit or modify your application's code.

Has ConfigCat proven itself in the real world?

The short answer is, yes! ConfigCat has been used by many companies to perform more than just staged rollouts and canary releases. is one of those companies. In the blog article ' Moves Faster than Their Competition', they describe that before deploying to production, they would turn flags on for internal users using ConfigCat and run one last smoke test. Once satisfied, they'll enable the flags for all users. Many other companies are also using ConfigCat in similar ways; you can read more here.


Staged rollouts and canary releases are effective strategies for testing new features and updates before rolling them out to all users. The benefit of both strategies is that they allow for testing in production on real users, which is the best way to get feedback on how a new feature or update is working. With the power of feature flags and the targeting capabilities of ConfigCat, these strategies can be seamlessly integrated into any development workflow.

As we aim to improve software for end users, staged rollouts and canary releases will remain vital. The implementation of these strategies may often vary, but feature flags will undoubtedly remain a key component. In addition to what we've discussed, feature flags have many other applications, as they can also be used for A/B testing, dark launches, and more; the possibilities are endless. Furthermore, they are compatible with a variety of programming languages and popular technologies such as Azure, AWS, Zoho, and more.

Excited to give feature flags a try? You can get started with ConfigCat for free here. Deploy any time, release when confident. I have been using their free-forever plan in all my side projects and it has been great. You can also find more information on ConfigCat here.

Did you find this article valuable?

Support Chavez Harris by becoming a sponsor. Any amount is appreciated!