Sync schemas between two environments

This article explains how to update one schema with the other, for example, when you have a development and production environment with the same schema that is out of sync.

Introduction

In the event that you have separate environments, for example, Development, Testing, Acceptance, and Production, you may need to sync the schemas in these environments. You can do this automatically by running a sync process in Prepr. Choose to sync a schema with either the Sync schema with GitHub feature or the basic Sync schema process.

Use cases

Check out some of the use cases when you may need to synchronize your schema:

• Sync production to development

An example DTAP strategy is to maintain the schema in the Production environment and when the same content structure is needed for realistic test cases this schema needs to be copied to the Development, Test, or Acceptance environment. Learn more on how to set up a DTAP configuration.

• Sync development to production

After testing your development on the latest schema version in the Development or Test environments, it's possible that you may need to make changes to the schema. In this case, you could copy these changes to the Production environment.

• Share a schema between environments

Use the Shared schemas feature to maintain one schema across multiple environments, for example, for multiple brands. Check out more details in the environments doc.

To sync schemas in Prepr, use the Sync schema with GitHub feature or the Sync schema process detailed below.

Prerequisites

Make sure to enable the Schema permission in the environments where schemas will be synced. Check out roles and permissions in Prepr on how to do this.

Sync schema with GitHub

The process below shows you how to connect to your GitHub account and sync a schema using a GitHub repository.

Step 1: Generate a personal access token

To use a GitHub repository to sync schemas, follow the steps below to create a personal access token in your GitHub account.

1. Log in to your GitHub account and follow the GitHub docs to create a repository and necessary branches to manage your Prepr Schema.
2. In your GitHub account, click your profile photo to expand the sidebar menu on the right, and click the Settings link.
3. From the side menu on the left go to Developer Settings at the bottom. Expand the Personal access tokens option and click the Fine-grained tokens link.
4. Click the Generate new token button, enter a Token name (Max. 40 characters) to indicate the purpose of the token like Prepr Schema sync and select an Expiration for the token.
5. Under the Repository access section, choose the Only select repositories option and choose the repository you created earlier.
6. Under the Permissions section, expand the Repository permissions link, go to the Contents subsection and select an access level of Read and write.
7. Click the Generate token button and make sure to copy the generated token and save it somewhere safe. The token value will only be visible once.

Once done, you are ready to enable the GitHub sync in Prepr CMS.

Step 2: Connect to GitHub

The next step is to connect the Prepr CMS environment or organization to your GitHub account with the steps below.

1. Navigate to each environment or organization where schemas need to be synced.
2. Go to the Schema tab in the environment or the Shared schema tab in the organization and click the Enable GitHub sync link.
3. Sign in to your GitHub account, if you are not yet signed in.
4. Once connected, paste the token that you copied in the previous step and choose the repository and the branch to hold the most up to date schema.
5. Finally, set one of the following sync types: push, pull or push & pull.

• Choose push in the environment with the most up to date schema.
• Choose pull for any other schema that needs to be updated.
• Choose push & pull for the situation where you have schema updates from multiple development or testing environments.

Step 3: Push schema to GitHub repository

Once the GitHub account is connected to each of the applicable environments, you are ready to start the sync process.

1. Navigate to the environment or organization with the most up to date schema. This schema is typically the master version to sync all other schemas.
2. Click the GitHub sync dropdown. You'll see the repository and branch that you connected in the previous step.
3. Click the Push schema to GitHub button to push the current schema to the GitHub repository.

The repository will be updated as follows:

• If the repository is empty, the push request simply creates JSON files for each of the models, components, and remote sources in the schema.

  • The model JSON file names will match each model's Singular name in lowercase.
  • The component JSON file names will match their Type Name values in lower case.
  • The remote source JSON file names will match their Type Name values in lower case.

• If the repository already has JSON files, expect the following behavior:

  • If the JSON files match models, components, and remote sources in the schema, these JSON files will be overwritten.
  • If there are JSON files in the repository that don't have matching models, components, or remote sources, these JSON files will be removed from the repository.
  • For models, components, and remote sources that don't have matching JSON files, new JSON files will be created in the repository.

When successful, you'll see an All done! status message. Now your GitHub repository is up to date with the latest schema. And you can use this repository to sync any other schema in your organization by using a GitHub pull request.

Step 4: Pull schema from GitHub repository

If you want to update the schema in a Prepr environment or organization with the latest schema in the GitHub repository, navigate to that Prepr environment or organization. For example, if you want to update the Development schema with the latest production schema, navigate to the Development environment.

1. Click the GitHub sync dropdown. You'll see the repository and branch that you connected in Step 2.

2. Click the Pull schema from GitHub button to overwrite the schema in the current environment.

The schema will be updated as follows:

• Models, components, and remote sources will be overwritten with the matching JSON files in the GitHub repository. The pull request will find matching models, components, and remote sources using the model Singular name and the component and remote source Type name values in lower case.

• If there are JSON files that don't have a match in your environment or organization schema, new models, components, and remote sources will be created for each of these.

• If there are models, components and remote sources that don't have a matching JSON file, these will be automatically deleted if they are not in use by any content items.

That's it! You‘ve synchronized the schema using a GitHub repository.

Step 5: Push & Pull

In some cases, you may need to push your schema changes to the GitHub repository at one point and at a later stage pull other changes in the GitHub repository. For example, when testing schema changes during development. In this case, it's useful to be able to trigger either a push or a pull request in one environment where the connected GitHub branch could be a development branch or a backup branch instead of the main branch of the master schema.

The schema will be overwritten in the same way as detailed in the previous steps.

Schema sync

If you choose not to enable the GitHub sync feature, you can use the basic Sync schema process. Note the list of constraints below before triggering this process.

Constraints

• This process only works between environments in the same organization.

• Models in your target environment will be overwritten with the models from the current environment if their Singular names match. Some fields may be added or deleted to match a new structure.

• Components in your target environment will be overwritten with the components from the current environment if their Type names match. Some fields may be added or deleted to match a new structure.

• Models and components that are not in the current environment and present in the target environment aren't removed. You can choose to delete them manually if necessary.

• Content in your target environment will be updated to match the new schema.

The process below shows you how to sync your schema from one environment (current environment) to another (target environment).

Step 1: Choose the source schema

First, decide on the source schema and navigate to the environment in which it was created. This will be your current environment. For example, if you want to copy your Production schema to Development, navigate to the Production environment.

Step 2: Run the schema sync process

Once you’ve opened the chosen environment with the source schema, do as follows:

1. Go to Schema tab and click the Sync schema button at the top right. The Sync schema pop-up window will open.

2. In the pop-up window, ensure you read and understand all the syncing rules.
   
   

3. Select the target environment you want to sync your schema to. Here you can only choose from the environments of the same organization.
   
   

4. Click Sync schema to confirm and start the process.

Step 3: Check the result

After the sync is done, check the results. You can see which models and components were added or updated in your target environment.

Also, you can view models and components that only exist in your target environment. Prepr doesn't automatically remove or update these models and components when it synchronizes the schema. You can do it yourself later on if needed.

That's it! You‘ve synchronized the schema from your current environment to the target environment.

If you have any questions about schema synchronization, please reach out to our Support team.