Software Config Management
Software Config Management (SCM) enables you to push your Buzzy app changes from one deployment environment to another, such as from Development to Staging or from Staging to Production. This feature supports professional development workflows where you build and test in a safe environment before promoting changes to live users.
Why Use Software Config Management?
When building production applications, you typically want to separate your development work from what your users see. SCM allows you to maintain multiple environments (Development, Staging, Production) and control when changes move between them. This approach provides several benefits:
Safe Development: Make changes, experiment with new features, and fix bugs in your Development environment without affecting production users. Test thoroughly before promoting changes.
Quality Assurance: Use a Staging environment to perform final testing with real-world conditions before releasing to Production. Catch issues before they reach your users.
Controlled Releases: Decide exactly when changes go live. Push updates during low-traffic periods, coordinate releases with your team, and maintain full control over your deployment schedule.
Version History: Every push creates a version snapshot, allowing you to track what changed and when. If something goes wrong, you can reference previous versions.
How It Works
SCM operates on top of Buzzy's versioning system. When you push to another environment, Buzzy packages your app definition (screens, components, fields, actions, display rules) along with any associated files (images, assets) and applies them to the target environment.
Environment Flow Overview
The following diagram shows how changes flow from Development through Staging to Production:
What Gets Pushed
When you push a version between environments, the app definition and assets are always transferred. By default, user-related data stays in each environment, but you can optionally choose to include it:
Always pushed:
App Definition (screens, components, fields, actions, display rules)
Files & Assets (images, documents)
Optionally pushed (typically excluded):
Users
Teams
Organizations
Organization Membership
User Data (Datatables)
In most cases, you'll want to exclude user-related data so that each environment maintains its own users and data. This is the recommended approach for Development to Production workflows.
The Two-Stage Process
The process works in two stages:
Initial Setup: The first time you connect two environments, Buzzy performs a full setup that clones the database structure and creates a secure link between the environments. This is a one-time operation per environment pair.
Version Push: After setup, you can push specific versions of your app to the target environment. This transfers only the app definition and assets, not user data, allowing you to update the app while preserving the data in each environment.
Prerequisites
Before using SCM, ensure you have the following:
At Least Two Buzzy Deployments with Separate Database Clusters: SCM requires each deployment to have its own dedicated database cluster. To have a separate database cluster, you need either:
A Medium Deployment with the "Database Upgrade" add-on (contact [email protected] for more information)
A Large Deployment which includes a dedicated database cluster by default
See Buzzy Pricing for plan details and Create and manage Deployments for setup instructions.
App on Source Deployment: Your app must be associated with a source deployment. This is typically where you do your development work.
Appropriate Access: You must be either a global admin on the deployment or an owner/admin of the specific app you want to push.
Target Environment Configured: The target deployment must be configured to receive pushes (this is handled during the initial setup process).
Setting Up Your First Environment
The first time you want to push to a new environment, you need to run the Setup process. This creates the connection between your source and target deployments.
Step-by-Step Setup
Open your app in the Buzzy editor on your source deployment (for example, your Development server).
Navigate to the Publish panel in the editor sidebar.
Scroll to the Setup New Environment section.
Select your target deployment from the dropdown. The list shows all active deployments except your current one.
Configure optional exclusions if needed (see below).
Click Setup and confirm when prompted.
The setup process will clone your database structure to the target environment and establish a secure connection for future pushes. This may take a few minutes depending on the size of your database.
Optional Exclusions During Setup
When setting up a new environment, you can choose to exclude certain data from the initial copy:
Exclude Users
User accounts
When target has its own user base
Exclude Organizations
Organization records
When target has different organizations
Exclude Teams & Team Members
Team structures
When target has different team setup
Exclude Micro App Data & Child Data
All user-entered data
When you only want the app structure, not data
For a typical Development to Production setup, you might exclude user data so that your production environment starts fresh while receiving the app structure and configuration.
Pushing a Version to an Environment
Once setup is complete, you can push versions of your app to the target environment whenever you're ready to release changes.
Step-by-Step Push
Ensure you have saved a version of your app that you want to push. Use the Versions tab in the editor to create a version if needed.
Navigate to the Publish panel in the editor.
Scroll to the Push Version to Environment section.
Select the Version you want to push from the dropdown.
Select the Target Environment from the dropdown. Only environments that have been set up will appear here.
Click Push Version and confirm when prompted.
Buzzy will package your app definition, copy any associated files (images, assets), and apply the changes to the target environment. The target environment automatically creates a backup version before applying changes, so you can roll back if needed.
Viewing Push History
The Publish panel includes a Push History section where you can view all setup and push operations. This helps you track what was pushed, when, and whether it succeeded.
Understanding the History
The history shows three types of operations:
Setup Environment
Initial setup that cloned the database to a target
Push Version (Sent)
A version push you initiated from this environment
Apply Version (Received)
A version push this environment received from another
Click on any entry to expand details including timestamps, metadata, and any error information if the operation failed.
Typical Workflow Example
Here's how a typical three-environment workflow might look:
Development Environment (dev.yourcompany.buzzy.buzz)
This is where you build new features and fix bugs
Test changes thoroughly in preview mode
Save versions when features are ready
Staging Environment (staging.yourcompany.buzzy.buzz)
Push versions from Development when ready for QA
Perform user acceptance testing
Verify everything works with production-like conditions
Production Environment (app.yourcompany.buzzy.buzz)
Push versions from Staging after QA approval
This is what your end users see
Schedule pushes during maintenance windows if needed
Example Release Process
Build in Development: Create a new feature, test it in preview mode, fix any issues.
Save a Version: In the Versions tab, save a version with a descriptive name like "v2.3 - New dashboard feature".
Push to Staging: Use the Publish panel to push this version to your Staging environment.
Test in Staging: Have your QA team or stakeholders test the changes in the Staging environment.
Push to Production: Once approved, push the same version from Staging to Production (or push directly from Development if you don't use Staging).
Verify in Production: Confirm the changes are live and working correctly.
Working with Versions
SCM works hand-in-hand with Buzzy's versioning system. Understanding versions helps you use SCM effectively.
Creating Versions: Before pushing, save a version in the Versions tab. Give it a meaningful name that describes what changed.
Selecting Versions to Push: When pushing, you select which version to send. This lets you push a specific, tested version rather than your current work-in-progress.
Automatic Backup: When a target environment receives a push, it automatically creates a version snapshot before applying changes. This means you can always roll back if something goes wrong.
Version Independence: Each environment maintains its own version history. A version pushed from Development becomes a new version in Staging, independent of the source.
For more on versioning, see the Versions documentation in the editor guide.
Troubleshooting
"Target deployment is not configured as an environment"
This means you haven't run the initial Setup for this target deployment. Go to the Setup New Environment section and complete the setup process first.
"Source deployment ID is missing"
Your app isn't associated with a deployment. Ensure you're working on an app that's been published to a deployment, not just on app.buzzy.buzz.
Push succeeded but changes aren't visible
Try refreshing the target environment's browser. If using cached assets, you may need to clear your browser cache. Also verify you're looking at the correct environment URL.
Setup or push is taking a long time
Large databases or many assets can take several minutes to process. Check the Push History for status updates. If an operation seems stuck, contact [email protected].
"Invalid shared secret token" error
The secure connection between environments may have become invalid. Contact your administrator to use the Validate & Fix feature in the environment management tools.
Limitations
Configuration is Pushed "As-Is"
When you push a version from Development to Staging or Production, all configuration including action rules, URLs, and endpoints are transferred exactly as they exist in the source environment. This means:
External URLs and Endpoints: If your Development environment uses different URLs for external services (such as Lambda functions, webhooks, or third-party APIs), those Development URLs will be pushed to the target environment. Before pushing upstream, ensure you update any environment-specific URLs back to their production endpoints.
Example scenario: You're testing a new feature in Development that calls a Lambda function at https://dev-api.example.com/function. When you push to Production, that Development URL will be included. Your Production app would then call the Development API instead of the Production API.
Before pushing upstream, always review:
API endpoint URLs in your actions
Webhook URLs
External service configurations
Any hardcoded URLs that differ between environments
Important: Always verify that environment-specific configurations (URLs, API endpoints, webhook addresses) are set to their production values before pushing to Staging or Production environments.
Best Practices
Always test before pushing: Use preview mode in your source environment to verify changes work correctly before pushing to another environment.
Use meaningful version names: When saving versions, use descriptive names that help you identify what changed. This makes it easier to select the right version to push.
Document your releases: Keep notes about what each push includes, especially for production releases. This helps with troubleshooting and team communication.
Schedule production pushes: For production environments with active users, consider pushing during low-traffic periods to minimize any potential disruption.
Maintain environment parity: Try to keep your environments as similar as possible in terms of configuration. This helps ensure that what works in Staging will work in Production.
Review environment-specific settings before pushing: Check that any URLs, API endpoints, or external service configurations are appropriate for the target environment before pushing upstream.
Related Documentation
Create and manage Deployments - Set up the deployments you need for multi-environment workflows
Publish your app to your Deployment - Initial publishing from app.buzzy.buzz to your deployment
Setting up your custom Buzzy app - Configure domains, email, and other deployment settings
Last updated