User Story Bundle Introduction

Updated 1 month ago by Copado Solutions


User Story Bundle is meant for organizations that have a large number of user stories per release to promote and back promote. This feature enables organizations to simplify and speed up the entire production release process. It enables users to group large amounts of changes and helps in reducing time and complexity in promotions making it a good fit for customers who like the idea of packages but are not yet ready to start using Salesforce DX packages.

Customers who need to centralize changes from several user stories into a single user story can leverage the user story bundle feature.


  • Groups 50+ user stories into a single bundle to reduce promotion complexity.
  • Reduces merge conflicts and speeds up creating promotions. You can see up to 90-95% efficiency improvement in creating promotions and deployments. 
  • As promotion creation complexity is reduced, release stability improves.
  • Bundles consider regular commits, as well as full profile and deletion commits.
  • Deployment tasks of the user stories are mirrored on the user story bundle.
  • Source stories are deactivated but status and environments are synchronized with the user story bundle.
  • Upon promotion, user story bundles merge with changes in the target branch.
  • Metadata can stay as happy soup (unpackaged) metadata.


  • Faster releases and promotions on higher environments
  • Faster back promotions.
  • Less merge conflicts.
  • Keep source user story history auditable through all the stages.
  • Keep the source user story in JIRA/Azure updated with the Copado user story status.
  • Keep track of additional tasks for the release.

Functional Details

Considerations Around Using User Story Bundles
  1. Git history of the original user story feature branches does not continue up the pipeline. Feature branches still remain in the repository for auditing purposes.
  2. Stories should be bundled on an org without work in progress for future releases or with it not being part of the selections in your bundle. Otherwise, the user story bundle might pick up part of the work in progress which will lead to failing deployments.
  3. When the bundle is Locked we perform a recommit of what is selected from the org into a feature branch.
    Do not use if you don't want work in progress to be committed.
  4. Source story environment and bundle environment, as well as pipelines, need to match.
  5. If you don’t want people to be able to create bundles, don’t give them Package / Package version creation access. Use custom permission sets if required.
  6. Fields on the Lock Bundle modal can be modified with a fieldset on the User Story object. This is handy if you want to directly set the bundle status, bundle base branch, or the ready to promote flag.
  7. Bundles support source format.
  8. User stories included in a bundle that are part of a promotion do not have to be added separately to the promotion if they are already in the bundle or it will give you an error.
  9. 300+ user stories can sometimes not be bundled together if the files are very large (e.g. static resources, 200MB+ profile files):
    1. The recommit job may not complete when it exceeds the memory limit due to very large files.
    2. In this case, bundle the user stories into 2 or more bundles.
Known Gaps
  • Data commits are partially supported. 
  • Base branch check is not applied during bundle creation

How did we do?