Change Sets

Group related changes across commits and track them through deployment environments.

Overview

A change set is a logical grouping of related commits that together implement a feature, fix a bug, or update a configuration. Change sets bridge the gap between individual commits and deployable versions.

While commits are atomic snapshots of code changes, change sets represent complete units of work that can be:

Reviewed as a whole — All related changes visible together
Promoted as a unit — Move from dev to staging to production as one package
Tracked across environments — See which environments have which features
Rolled back together — Undo entire feature sets, not just individual commits

Why Change Sets?

Consider a workflow enhancement that requires:

New LLM prompt (commit A)
Updated workflow DAG (commit B)
Modified configuration (commit C)
Documentation update (commit D)

These four commits are related and should be deployed together. A change set groups them for coordinated deployment.

Creating a Change Set

Navigate to Manage → Repositories → [Repository] → History and identify commits that belong together.

Create Change Set

From the Change Sets tab, click New Change Set.

Configure Change Set

Provide:

Name — Descriptive identifier (e.g., fraud-detection-v2)
Description — Summary of what the change set accomplishes
Included commits — Select commits from the list
Tags — Optional labels for categorization (e.g., feature, bugfix, performance)

Save

The change set is created and appears in the change set list.

Change sets can span multiple branches if related work happened in parallel and was merged.

Change Set Contents

A change set displays:

Commit List

All commits included in the set, with:

Commit hash (short SHA)
Author
Timestamp
Message

Combined Diff

Aggregate diff showing all changes across all commits. Useful for reviewing the complete scope of work.

Affected Files

List of files modified, added, or deleted by any commit in the set.

Metadata

Created by — User who created the change set
Created at — Timestamp
Status — Draft, Ready, Deployed

Change Set Lifecycle

Change sets progress through several states:

Status	Description	Actions Available
Draft	Work in progress	Add/remove commits, edit description
Ready	Complete and ready for promotion	Create version, deploy
Deployed	Promoted to at least one environment	View deployment history
Superseded	Replaced by newer change set	View for historical reference

Draft

Initial state when change set is created. Continue adding commits as work progresses.

Ready

Mark change set as ready when:

All planned commits are included
Changes have been tested locally
Pull requests are merged (if applicable)

Ready change sets can be promoted to versions.

Deployed

Automatically transitions to deployed when a version is created from the change set and deployed to an environment.

Superseded

When a newer change set includes overlapping commits or replaces functionality, the older set is marked superseded.

Promoting Change Sets

Change sets integrate with the Release Pipeline for environment promotion:

Create Version from Change Set

From the change set view, click Create Version. This:

Snapshots all commits in the change set
Generates a version identifier (e.g., v1.3.0)
Tags the repository at the latest commit in the set

Deploy to Staging

In the Release Pipeline, select the version and deploy to staging environment:

System pulls artifacts from Git at the tagged commit
Applies configuration for staging
Deploys workflows, prompts, agents to staging infrastructure

Validate in Staging

Test the deployed change set:

Run workflows and verify behavior
Check monitoring dashboards
Execute integration tests

Promote to Production

If staging validation passes, promote the same version to production. The change set moves as a unit.

Always deploy change sets to staging before production. Never skip environments.

Tracking Change Sets Across Environments

The Change Set Tracker shows which environments have which change sets:

Change Set	Dev	Staging	Production	Status
`fraud-detection-v2`	✓ Deployed	✓ Deployed	✗ Not deployed	Ready for prod
`multi-lang-prompts`	✓ Deployed	✗ Not deployed	✗ Not deployed	Awaiting staging
`performance-tuning`	✗ Not deployed	✗ Not deployed	✗ Not deployed	Draft

This provides a clear view of what’s where and what needs promotion.

Use Cases

Feature Deployment

A new feature spanning multiple files:


Change Set: "RAG Pipeline Integration"
Commits:
  - Add vector database connector
  - Implement semantic search workflow
  - Create RAG prompt templates
  - Update configuration schema
  - Add integration tests

Deploy as one unit to ensure all components arrive together.

Bug Fix

A critical fix requiring changes in multiple places:


Change Set: "Fix workflow timeout handling"
Commits:
  - Increase timeout thresholds in config
  - Add retry logic to API call node
  - Update error messages

Group commits so the fix deploys completely or not at all.

Configuration Update

Environment-specific configuration changes:


Change Set: "Enable GPT-4o for production"
Commits:
  - Update LLM connection configs
  - Adjust token limits for new model
  - Update cost tracking rules

Promote together to avoid partial configuration.

Best Practices

Keep Change Sets Cohesive

Each change set should represent one logical feature or fix. Avoid:

Mixing unrelated changes — Don’t combine a bug fix and a new feature
Too many commits — If over 20 commits, consider splitting into multiple change sets
Overlapping change sets — Don’t create multiple sets with the same commits

Name Descriptively

Change set names should clearly describe the work:

Poor:


Updates

Good:


Add multi-language support to extraction workflows

Add Context in Descriptions

Include:

What the change set accomplishes
Why it was needed
How to verify it works
Dependencies on other systems or change sets

Example:


## Summary
Adds support for processing invoices in Spanish, French, and German.
 
## Motivation
Customer expansion into European markets requires multi-language extraction.
 
## Changes
- New prompt templates for each language
- Language detection node in workflow
- Updated configuration with language-specific models
 
## Testing
- Run sample invoices in each language through workflow
- Verify extraction accuracy meets 95% threshold

Version Change Sets

When creating versions from change sets, use semantic versioning:

Major (v2.0.0) — Breaking changes
Minor (v1.3.0) — New features, backward compatible
Patch (v1.2.1) — Bug fixes, backward compatible

Match version numbers to change set scope.

Integration with Pull Requests

Pull requests and change sets work together:

Create feature branch for related work
Commit changes iteratively during development
Open pull request for review
Merge PR to main after approval
Create change set from merged commits
Promote change set through environments

The PR provides code review; the change set provides deployment tracking.

Rollback with Change Sets

To rollback a deployed change set:

Identify Change Set to Rollback

In the change set tracker, find the problematic change set currently in production.

Create Revert Change Set

Create a new change set containing revert commits:

Git revert each commit in the original change set (in reverse order)
Group revert commits into a new change set
Name it clearly (e.g., Revert: fraud-detection-v2)

Deploy Revert

Promote the revert change set through environments just like a forward change set:

Deploy to staging
Validate rollback
Promote to production

Never use git reset or force push to rollback production. Always use revert commits in a new change set to maintain history.

Troubleshooting

Missing Commits

Cause: Forgot to include related commits in change set.

Solution: Edit draft change set and add missing commits before marking ready.

Overlapping Change Sets

Cause: Two change sets include the same commits.

Solution: Reorganize change sets to have clear boundaries, or accept overlap if changes are truly independent.

Failed Deployment

Cause: Change set deployed to staging but encountered errors.

Solution: Do not promote to production. Create a fix as a new change set or revert.

Next Steps

Learn the Release Pipeline for environment promotion
Set up pull request workflows
Configure repository webhooks to auto-create change sets on merge
Implement automated testing before change set promotion