User Story Bundle

Updated 1 month ago by Copado Solutions


User Story Bundle (USB) is meant for organizations that have a large number of user stories (US) per release to promote and back promote. This feature enables organizations to simplify and speed up the entire production release process. USB 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 USB feature.

Features of USB

  • 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 US are mirrored on the USB.
  • Source stories are deactivated but Status and environments are synchronized with the USB.
  • Upon promotion, USBs 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 and measurable (DevOps360) 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.

Workings of a User Story Bundle

Functional Details

Identify How to Best Group User Stories in a Bundle
  • Define by which criteria to bundle them:
    • Common sprint
    • Common release
    • Common project
    • Common functionality
    • Common dependencies
  • Define in which stage of the pipeline it is more suitable to bundle the story. It is recommended that User Stories get bundled in a stable environment with little or no work in progress. For example, on the UAT org after a sprint or a release has been successfully tested.
Create a User Story Bundle
  1. Go to the User Story list view.
  2. Select all the User Stories you want to bundle and ensure they all are Ready to Promote.
  3. Click the drop-down arrow for more action buttons and select Create Bundle.
  4. Now enter a name without any space, for the new USB.
  5. This generates a package in the Package Version record. Here in the USB section, you can view the User Story you selected.
  6. Confirm all the details and click Lock Bundle.
    The Lock Bundle modal is prefilled based on some pre-defined conditions as explained below:
    1. If all the values of Release, Project and Credentials are the same across all User Stories inside a bundle, the same values are populated in the modal.
    2. If any value is missing in any of the User Stories, or if the values are different across the User Stories in the bundle, or if both conditions are applicable across the User Stories, you will be required to enter the value manually.
    3. If you try to enter a different Environment value manually, it will give you an error.
  7. Click Lock Bundle. The USB will be generated and the combined selections of your initial stories will be committed into a new feature branch. This will take place on the org where the stories are bundled. Depending on the type of commits and selections, this can take more than a regular commit, especially if you have many full-profile commits.
  8. Now you have a new US with these features:
    1. The record type is Utility.
    2. Is Bundle is selected. 
    3. There is a feature branch.
    4. There are User Story selections attached to this type of User Stories where you can view all the User Stories you selected earlier.
    5. If your initial stories had deployment tasks, the combined deployment tasks will be mirrored on the USB.


If you navigate to the original user stories, you will notice the following:

  • The Exclude from CBM and Stop Indexing Metadata in the child User Stories are selected.
    • The User Stories don’t appear in the pipeline, as only the USB is promoted and back promoted.
  • The Status, Org Credential, and Environment fields of the original User Stories get automatically updated as the User Story Bundle is promoted to higher environments.
Cancel a User Story Bundle

There can be cases where you want to change or un-do a bundle. In order to achieve this, it can be beneficial to cancel the existing bundle that locks the US.

To cancel a bundle perform the following steps:

  1. Go to the USB.
  2. Change the Status to Cancelled.
  3. Click Save.
  4. Go to the User Story list view, you will find the Exclude from CBM and Stop Indexing Metadata fields are unchecked for the previously selected User Story and they are ready to be selected for a new USB.

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 (WIP) for future releases or with the WIP not being part of the selections in your bundle. Otherwise, the USB might pick up part of the WIP 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 WIP 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. 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?