---
title: "Configure role serialization"
slug: "configure-role-serialization"
abstract: "How to serialize roles in your project."
---
# Configure role serialization

It is possible to serialize roles so that sync operations include the specified roles. Serialization lets developers and DevOps engineers manage roles in their solution by synchronizing roles with other developers on the same project. It lets them promote changes to source-controlled roles across Sitecore environments.

> [!note]
> This feature is available from CLI 4.0 or later and is currently unavailable for creating `*.dat` files. From version 4.1, the Sitecore CLI supports the inclusion of serialized roles in an item package.

<details>
<summary><h2>Configure roles in *module.json files</h2></summary>

You can define which roles to include in the serialization process. You can specify roles in any `*module.json` configuration file. The `roles` property is an array that consists of role predicate items with two properties:

- `domain` (Sitecore role domain)
- `pattern` (a regex pattern to determine specific roles to include under the domain)

> [!important]
> You must make sure your local environment is up-to-date before making changes. Defining a pattern such as `^.*$` and performing a `push` command before a `pull` command (so that serialized roles are not present on your computer) deletes all roles staged for removal from the Sitecore instance.

To set up roles in a `*module.json` configuration file:

- Inside the root section, specify the `pattern` and `domain` role properties. For example:

    ```json
    {
        ...
        "items": {
            ...
        },
        "roles": [
          {
            "domain": "sitecore",
            "pattern": "Developer"
          },
          {
            "domain": "custom",
            "pattern": "Role*"
          },
          {
            "domain": "extranet",
            "pattern": "^MySite.*$"
          }
        ]
    }
    ```

> [!important]
> Nonserialized orphaned roles that match the configuration predicate are automatically deleted from Sitecore.

> [!warning]
> The Sitecore CLI allows you to serialize roles in a custom security domain. However, the custom domain will not be created automatically with the push command. To make sure the roles function correctly, manually [create a security domain](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/create-and-edit-a-security-domain.html) in your target environment.

</details>

<details>
<summary><h2>Check role serialization</h2></summary>

To check the summary of the role data:

- Run the `serialization info` command. Output:

    ```

    ModuleWithRole
      Subtrees:
        ...
      Roles: 1
    ```

To check the full details of the role data:

- Run the `serialization info -t` command. Output:

    ```

    Maximum subtree-relative item path allowed: 120

    ModuleWithRole
        File: C:\Projects\Example\serialization\src/ModuleWithRole/ModuleWithRole.module.json
        Subtrees:
            ...
        Roles:
            domain :extranet
            pattern:^MySite.*$
    ```

</details>