Skip to main content
A promotion (also called a configuration push) proposes configuration changes from a source workspace for review, then applies them to a target workspace. You can promote between any two linked workspaces.

​
Set up

To group promotion features in the sidebar, open Settings → Capabilities → Test & Release. For workspaces that require Catalyst reviews, have a linked workspace, or already use promotion reviews, it turns on automatically and can’t be turned off. Other workspaces can opt in manually. This setting only groups features in the sidebar, but it doesn’t grant permissions.

​
Propose a change

1

Make your changes

Edit configuration in the source workspace. Publish workflows, skills, and forms before you promote them, so the promotion carries your published versions. Run any relevant simulations or workflows to test first.
2

Start a promotion

Choose the target workspace in the destination picker. The comparison page loads the differences and shows any blockers.
3

Review the differences

The comparison shows what will change. Include the dependencies your changes need (see Include the right dependencies). For a skill’s audience change, the review’s Preview shows Can be used for with the current and proposed access profiles.
4

Propose for review

Select Propose for review. Serval drafts a title and description you can edit before you Propose.

​
Review and apply

Before a promotion is applied, its review can require two independent gates (configure them in Getting started):
  • Approvals: assigned approvers sign off before anything changes in the target workspace.
  • Checks: a workflow or an evaluation suite must pass first.
A member of the target workspace with appropriate permissions applies the review, and the changes take effect. A promotion applies resource by resource. If some resources fail, the successful ones take effect and the failed ones remain at previous versions. You can retry the review or create a fresh one. A completed review keeps its recorded check results, so a later policy change doesn’t require rerunning it. When a review’s last run contained no checks, it shows No checks in last run. The proposer can Withdraw a promotion they proposed, and promotion reviews don’t support requesting changes. For how a target workspace approves or rejects a promotion, see Changes and reviews. Promotions are forward-only: there’s no undo once a review is applied. To revert, promote the previous configuration again. Revoking a workspace link doesn’t undo configuration that was already applied. Managers configure required checks and, where enforcement controls exist, turn enforcement on or off. Builders can author and stage changes but need the Manager role to manage the workspace’s check policy. Managers and organization admins set workspace protection in Settings → Your Workspace → Workspace protection.

​
Include the right dependencies

While you review the differences, include the dependencies your selected changes rely on in the target workspace. Serval can offer to add them. When you select Propose, it stops for problems you must fix first:
  • A reference missing in the source workspace. The comparison identifies it on the affected resource. Restore the dependency or remove its reference, then reload the page to update the comparison.
  • A name conflict. If a selected access policy has the same name as a different policy in the target workspace, Propose stops before creating a review. Rename one of the policies in its own workspace, refresh the comparison, and try again. Skill names are checked the same way: rename the skill in the source workspace, publish it, refresh, and propose again.

​
Delete configuration through a promotion

A comparison shows supported resources that exist only in the target workspace. Select one to delete it through the promotion. Nothing is deleted until the review is applied. Deleting an app resource also deletes its roles, including roles that exist only in the target workspace. You can select an individual role for deletion when you aren’t deleting its parent. Serval enforces deletion restrictions when the review is applied, so a change made after you create the review can still block it. A blocked deletion shows its reason. For example:
  • A schedule still in use. Move the affected SLA rules, requester follow-up settings, or assignment group schedules to another schedule in the target workspace, then retry the failed change.
  • A provisioning or deprovisioning workflow assigned to a role. Reassign those roles before you delete their workflows.
Other resources that still refer to a deleted item can remain and may fail when used. Resource types without deletion support appear in the comparison but can’t be selected.

​
Promote to the next workspace

On an applied promotion review, select Promote to [workspace name] to create the next review in one click. For example, after applying a review into Staging, select Promote to Production. The new review keeps the title and description, so you don’t select the resources or Propose again. The new review uses the current published configuration of the original review’s resources. Unrelated changes already in Staging aren’t included. Resources that already match the next workspace are skipped, and if they all match, no review is created. The receiving workspace’s own approvals and apply process still apply. The action appears when promotions are enabled, you can create promotions from the receiving workspace, and that workspace has a single, unambiguous onward destination.

​
How integrations are handled

Copied connections start with syncing turned off. Serval doesn’t copy credentials for OAuth refresh tokens, user-impersonation configurations, shared-source credentials, or cross-organization transfers. When a credential can’t be copied, connect a matching integration in the target workspace: open Integrations there, connect the same external account with its own authorization, then refresh the comparison and propose again. For a User OAuth connection, each user connects their own account in the target workspace. If a workflow’s custom app is missing in the target, promote the custom service and app instance first (or, for an app shared from another workspace, ask that workspace’s administrator to share it), then retry the failed workflow.
Copied connections reach the same external system and can perform writes. Point the target workspace at a separate test account when you need isolated testing.

​
Across organizations

Promotions can also move configuration between workspaces in different organizations, for partners and managed setups. Serval links the two organizations, and an admin in each then exchanges a single-use invite code to connect the workspaces. Serval never copies credentials across organizations: connect a matching integration in the target organization yourself.

​
Troubleshoot failed changes

  • A ticket type is turned off in the target workspace. When a status set can’t apply because its ticket type is turned off, turn that ticket type on in the target workspace’s Settings → Capabilities, then retry the failed change. Turning it on in the source workspace doesn’t turn it on in the target.
  • An access profile references a deleted group. The failed change names the group and workspace. In the source workspace, replace the deleted group with the intended active group, keeping the profile’s access restriction, and publish the fix. A saved review keeps its original snapshot, so retrying the old review won’t include the repair: restage a fresh promotion from the repaired source, then apply it to the target workspace.
  • An integration identity is reserved in the target. Copy the support reference from the error and contact support. Renaming or deleting the resource doesn’t release the identity, and retrying alone can’t resolve it. Other independent changes still apply.