Help Center / Reuse content structures / Merge app

The Merge app

Overview

The Merge app allows you to move your content type changes from one environment to another. With the Merge app, you can review the changes in your non-production environment and select which ones to merge to the target environment that you select.

The following kinds of content type changes are included in the merge:

  • Adding, editing, changing and/or deleting content types.

  • Adding, editing and/or deleting fields.

  • Adding, editing and/or removing field settings and validations.

  • Default value edits.

  • Change of field appearance and help text.

Requirements

  • A minimum of two environments in the same space, with the Merge app installed in each environment to be used for comparing changes.

  • For a user to be able to perform a merge, the following permissions need to be activated in this user's space role:

  • Allow rule to read all entries in the target environment.

    NOTE: If access to any of the entries in the target environment is denied, the Merge app will not be able to validate whether a merge can be executed successfully.

  • Permission to create, edit and delete content types in the target environment.

Install the Merge app

To install the Merge app:

  1. Log in to the Contentful web app.

  2. In the top pane, click Apps and select Marketplace.

  3. Navigate to the Merge app and select it. The “App details” page is displayed.

  4. Click Install. The “Manage app access” modal is displayed.

    Merge app: Manage access

  5. Click the Environments drop-down menu and select the one(s) in which you want to install the Merge app.

  6. Click Authorize access.

    NOTE: It is required to install the Merge app in an environment to use it as a source or target environment for content type changes.

  7. In the app information page, click Install. The Merge app is installed.

    Merge app: Install app

NOTE: Whenever you clone an environment, if you have the Merge app installed, it also gets cloned.

Merge content type changes

Merging your content type changes from one environment to another requires going through the following stages in the app:

  • Selecting the environments — In this stage, you select the source environment which contains the changes and the target environment to which you would like to merge your changes.

  • Selecting the content types — In this stage, you compare your content types and select the changes that you would like to merge to the target environment.
    The changes are highlighted to reflect the change type as follows:
    - Blue color — Highlights a content type or a field that is updated in a merge.
    - Green color — Highlights a content type or a field that is added in a merge.
    - Red color — Highlights a content type or a field that is deleted in a merge.

  • Resolving conflicts — In this stage, you can review potential conflicts and read the recommendations to resolve them. The content types are displayed under the following groups:

    1. Content types with required actions — It is required to fulfill the instructions under this section to merge the content type to the target environment.
      Alternatively to fulfilling the instructions, you may remove the content type from your merge.

    2. Content types with recommended actions — It is recommended to fulfill the instructions under this section, but the content type will be merged in any case.

    3. Ready to merge — The content type has no conflicts. No action required.

NOTE: You can also use the Merge app with the Contentful CLI. For more information, see Merge app CLI.

How to merge content type changes

To merge your content types changes from one environment to another:

  1. Log in to the Contentful web app.

  2. Click Apps and select Merge.

  3. Select the environments for merging from the drop-down lists under the following fields:

    1. Target environment — Select the target environment to merge your changes to.

    2. Source environment — Select the environment in which the changes were made.

  4. After both source and target environments are selected, click Compare environments.

  5. Select the checkboxes of the content type changes you want to be merged.

    NOTE: Clicking Show details expands the details of a specific change, where you can view which fields were added, removed or edited.

  6. Click Review changes to proceed to the next step.

  7. If there are any conflicts, review and resolve them as instructed, and click Reload page to update the page.

    Important: It is mandatory to resolve conflicts under the “Content types with required actions” to be able to proceed with your merge. Alternatively, you can remove the content types from the merge.

  8. Optional: Click Export migration script to generate and download the migration file. You can use the migration file to apply your content type changes in other environments or spaces or to keep a record of the migration.

  9. Click Merge content types. The “Merges are final” modal is displayed.

  10. Click Merge content types to confirm your changes. The merging process starts.

    Important: Don’t close the browser tab until the merge is finished.

  11. Optional: After your content type changes are merged to the target environment, look through the results of the merge in the MERGE RESULT screen.