Environment support for Cross-space references

Table of contents

• Environments with Cross-space references
• How to copy an environment containing cross-space links
• How to repoint a master alias to another environment: aliased environments
• How to repoint a master alias to another environment: non-aliased environments
• How to delete an environment
• How to merge two environments
• How to add a master alias in an existing setup with references
• How to import entries and content types

Environments with Cross-space references

You can use cross-space references to point to non-master environments and carry out testing and staging changes across spaces in the content development workflow. This article contains a few use cases of the extended environment support to show you how you can use the feature in your content development.

For all of the example scenarios, we assume the user has:

• three spaces linked together using cross-space links
• access to all of these spaces
• permissions to create new environments
• properly set up the Contentful CLI and the Merge app CLI
• already selected the main space to work on via the contentful space use.

How to copy an environment containing cross-space links

Consider the following scenario:

• You have three spaces, Space A, Space B and Space C that are linked together using cross-space links, with Space A being the main space.
• The cross-space links are linked between the "master" environments of these three spaces.

When copying the "master" environment of Space A, it is copied as a new environment called, in this case, "master-new", as pictured below:

The cross-space links in the "master-new" environment are the exact same copy of the source environment (master), meaning they all point to other "master" environments. This setup works because the new environment has the identical content types, entries and references. However, if you want to have a mirrored setup, you must take some additional steps. A mirrored setup means having a copied environment point to another copied environment, as pictured below:

Workflow

To have your copied environment point to another copied environment:

1. In the Contentful CLI, use the following command to create a copy of the "master" environment in Space A: contentful space environment create --source master --environment-id 'master-new' --name 'master-new'. The copy environment is called "master-new".

2. Switch to Space B using the following command: contentful space use spaceB.

3. Copy the "master" environment in Space B: contentful space environment create --source master --environment-id 'master-new' --name 'master-new'.

4. Switch to Space C using the following command: contentful space use spaceC.

5. Copy the "master" environment in Space C: contentful space environment create --source master --environment-id 'master-new' --name 'master-new'.

6. Update the references between the linked environments.
   

   How to repoint a master alias to another environment: aliased environments

   Consider the following scenario:

• You have three spaces, Space A, Space B and Space C that are linked together using cross-space links, with Space A being the main space.
• Every space has two environments, one of them being aliased as "master".
• The cross-space links are linked between the "master" aliases of these three spaces.

Workflow

To have the "master" alias of the main space, Space A, point to another environment and all the linked references to also reference "master" aliases from other spaces:

1. In the Contentful CLI, use the following command to repoint the "master" alias environment in Space A to the new environment: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

2. Switch to Space B using the following command: contentful space use spaceB.

3. Update the alias for "master" to point to the desired environment in Space B: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

4. Switch to Space C using the following command: contentful space use spaceC.

5. Update the alias for "master" to point to the desired environment in Space C: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

6. Switch to Space B again and update the reference to point to the aliased "master" environment.

7. Switch to Space C and update the reference to point to the aliased "master" environment.

How to repoint a master alias to another environment: non-aliased environments

Consider the following scenario:

• You have three spaces, Space A, Space B and Space C that are linked together using cross-space links, with Space A being the main space.
• Every space has two environments, one of them being a non-aliased "master".
• The cross-space links are linked between the "master" environments of these three spaces.

To have the "master" alias of the main space, Space A, point to another environment and all the linked references to also reference "master" environments from other spaces:

1. In the Contentful CLI, use the following command to repoint the "master" alias in Space A to the new environment: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

2. Switch to Space B using the following command: contentful space use spaceB.

3. Merge changes from the new environment into "master" for Space B.

4. Switch to Space C using the following command: contentful space use spaceC.

5. Merge changes from the new environment into "master" for Space C.

6. Update the references in the main space to point to "master" environment of Space B.

How to delete an environment

Consider the following scenario:

• You have two spaces, Space A and Space B that are linked together using cross-space links, with Space A being the main space.
• The main space, Space A has two environments.

Workflow

To delete one environment in Space A, use the following command in the Contentful CLI: contentful space environment delete --environment-id <environment-id>

How to merge two environments

Consider the following scenario:

• You have two spaces, Space A and Space B that are linked together using cross-space links, with Space A being the main space.
• The main space, Space A has two environments which have diverged.

Workflow

To merge two environments:

1. Generate the script using this command: contentful merge export --source-environment-id master-new --target-environment-id master.
2. Run the migration script: contentful space migration --space-id <my-space-id> migration-file.js.

How to add a master alias in an existing setup with references

Consider the following scenario:

• You have at least two spaces, Space A, Space B, that are linked together using cross-space links, with Space A being the main space.
• The space being referenced from the main space has two environments, one of them being a non-aliased "master".
• The cross-space links are linked between "master" environments of these two spaces.

If you want to introduce a "master" alias to a space with previously non-aliased "master" environment that was referenced from other spaces, we recommend you review any changes made to the "master" alias. This can lead to having the main space referencing non-obvious content. Initially, it was referencing explicit "master" environment of Space B, but the alias can be repointed.

The alias gets repointed to a different environment, and behind the scenes, Space A starts referencing different content.

How to import entries and content types

You can use additional tools to export and import content between spaces. For example, you can use the contentful space export CLI command or the contentful-export package directly. We recommend you review any diffs or files generated by those tools for the occurrences of cross-space links. The environments used in those links should be updated before using them as a source of truth for importing.