> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Link workspaces and configure review gates before you promote configuration.

Before you can promote configuration between workspaces, link the workspaces involved. You can also require approvals or checks on what a workspace receives.

## Link workspaces

A promotion is only allowed while an active link exists from the source workspace to the receiving workspace. Manage links in **Settings → Workspace Links**.

### Link workspaces in your organization

Linking two workspaces in the same organization (for example, a staging workspace and a production workspace) requires that you be an admin or a manager on both workspaces.

**1. Open Workspace Links**

In either workspace, go to **Settings → Workspace Links** and select **Add connection**.

**2. Choose the direction and workspace**

In **Add workspace connection**, choose **Receive configuration in \[workspace]** or **Send configuration from \[workspace]**, select **Link a workspace in your org**, and pick the other workspace.

### Link workspaces in another organization

Workspaces in different organizations connect with a single-use invite code. The receiving workspace generates the code, and the sending workspace redeems it.

> [!NOTE]
>
> Serval connects your organizations before cross-organization links will work. If the sending workspace can't redeem the code (for example, because cross-organization links aren't enabled for the organizations, or the two organizations aren't connected), contact Serval to connect your organizations first.

**1. Generate a code (receiving workspace)**

An admin or manager of the receiving workspace opens **Settings → Workspace Links → Add connection** and, under **Receive configuration in \[workspace]**, selects **Generate invite code**, then **Generate code**. Copy the `svl_` code (it's shown only once) and share it with the sending workspace over a trusted channel. The code is single-use and expires.

**2. Redeem the code (sending workspace)**

An admin or manager of the sending workspace opens **Settings → Workspace Links → Add connection** and, under **Send configuration from \[workspace]**, selects **Redeem invite code**, pastes the code, selects **Look up** to confirm the receiving workspace, then selects **Link workspaces**.

Once linked, the sending workspace can promote configuration into the receiving workspace, and the sending workspace's managers can view the receiving workspace's configuration to prepare promotions. Cross-organization promotions also require the receiving workspace to [require approval](#require-approval-for-promotions). Without an approval policy and an approver, these promotions are blocked.

### Revoke a link

To stop a workspace from sending configuration, select **Revoke**. Staged promotions that haven't been applied will fail, and you can link the workspaces again later. Revoking doesn't undo configuration that was already applied. Only manually created links can be revoked.

## Require approval for promotions

To require sign-off before a promotion is applied to a workspace, set an approval policy on the receiving workspace. A manager or admin of the receiving workspace can do this:

**1. Open Approval settings**

In the receiving workspace, open the **Reviews** page and select **Approval settings**.

**2. Set the incoming-promotions policy**

Select **Incoming promotions**, turn on **Require approval for incoming promotions**, choose an approval procedure with at least one approver, then select **Save changes**.

This approval is configured independently from Catalyst review approvals.

## Require checks on promotions

You can require a workflow or an evaluation suite to pass before a promotion is applied. Configure checks on the receiving workspace's **Reviews** page. Managing the check policy requires the Manager role.

**1. Open Promotion checks**

In the receiving workspace, open the **Reviews** page and select **Promotion checks**.

**2. Select the checks**

Select the checkbox next to each workflow or evaluation suite that must pass. For an evaluation suite, set the **Minimum pass percentage**: the share of its evaluations that must meet their expected result. Missing scores count against the total, and execution errors always fail the check.

**3. Require the checks to block**

If your workspace has enforcement controls, turn on **Require promotion checks** so a failing check blocks the promotion. Without it, selected checks still run but don't block. You can also mark an individual check optional.

## Related

* [Promotions overview](https://docs.serval.com/sections/documentation/platform/promotions.md)
* [Promote changes](https://docs.serval.com/sections/documentation/platform/test-and-release.md)
* [Changes and reviews](https://docs.serval.com/sections/documentation/catalyst/changes-and-reviews.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.