From e2ae2aff9fa4c7e2abcc3218347380547b303cb7 Mon Sep 17 00:00:00 2001 From: Michael Pham Date: Wed, 26 Aug 2026 13:27:23 -0500 Subject: [PATCH 1/4] docs: clarify embargoed asset migration [AIS-179] --- docs/space/export/README.md | 23 ++++++++++++++++++- docs/space/import/README.md | 16 ++++++++++++- lib/cmds/space_cmds/import.ts | 4 ++-- .../space/__snapshots__/import.test.js.snap | 18 ++++++++------- 4 files changed, 49 insertions(+), 12 deletions(-) diff --git a/docs/space/export/README.md b/docs/space/export/README.md index 9e665bdbd..68d23a126 100644 --- a/docs/space/export/README.md +++ b/docs/space/export/README.md @@ -66,6 +66,28 @@ Options: contentful space export ``` +### Embargoed assets + +When moving content from a space with [embargoed assets](https://www.contentful.com/help/media/embargoed-assets/), download the asset files during export. The corresponding import must upload those local files into the destination environment instead of asking the destination to fetch the source URLs. + +```sh +contentful space export \ + --space-id "$SPACE_ID" \ + --environment-id "$SOURCE_ENVIRONMENT_ID" \ + --download-assets \ + --export-dir ./contentful-export \ + --content-file content.json + +contentful space import \ + --space-id "$SPACE_ID" \ + --environment-id "$TARGET_ENVIRONMENT_ID" \ + --content-file ./contentful-export/content.json \ + --upload-assets \ + --assets-directory ./contentful-export +``` + +The `--assets-directory` value must be the directory generated by `--export-dir`. If an existing export contains embargoed asset URLs but no downloaded files, create the export again with `--download-assets`. + ## Exported data ```js @@ -84,4 +106,3 @@ contentful space export - This tool currently does **not** support the export of space memberships. - Exported webhooks with credentials will be exported as normal webhooks. Credentials should be added manually afterwards. - UI extensions will not be exported -- If a space is configured to use the [embargoed assets feature](https://www.contentful.com/help/media/embargoed-assets/), certain options will need to be set to use the space export/import tooling. When exporting content, the `downloadAssets` option must be set to `true`. This will download the asset files to your local machine. Then, when importing content, the `uploadAssets` option must be set to `true` and the `assetsDirectory` must be set to the directory that contains all of the exported asset folders. diff --git a/docs/space/import/README.md b/docs/space/import/README.md index b3656df4b..2bce113d9 100644 --- a/docs/space/import/README.md +++ b/docs/space/import/README.md @@ -51,10 +51,24 @@ contentful space import \ --content-file exported-file.json \ ``` +### Embargoed assets + +When importing content from a space with [embargoed assets](https://www.contentful.com/help/media/embargoed-assets/), the export must have been created with `--download-assets`. Pass both `--upload-assets` and `--assets-directory` so the importer uploads the local files into the destination environment. + +```sh +contentful space import \ + --space-id "$SPACE_ID" \ + --environment-id "$TARGET_ENVIRONMENT_ID" \ + --content-file ./contentful-export/content.json \ + --upload-assets \ + --assets-directory ./contentful-export +``` + +Without the downloaded files, the destination cannot process the source embargoed URLs and the import will fail before it starts with guidance for creating a portable export. + ## Limitations - This tool currently does **not** support the import of roles or space memberships. - This tool is expecting the target space to have the same default locale as your previously exported space. - Imported webhooks with credentials will be imported as normal webhooks. Credentials should be added manually afterwards. - If you have custom UI extensions, you need to reinstall them manually in the new space. Check this [link](https://www.contentful.com/blog/2016/07/06/ui-extensions-sdk/) on how to install them -- If a space is configured to use the [embargoed assets feature](https://www.contentful.com/help/media/embargoed-assets/), certain options will need to be set to use the space export/import tooling. When exporting content, the `downloadAssets` option must be set to `true`. This will download the asset files to your local machine. Then, when importing content, the `uploadAssets` option must be set to `true` and the `assetsDirectory` must be set to the directory that contains all of the exported asset folders. diff --git a/lib/cmds/space_cmds/import.ts b/lib/cmds/space_cmds/import.ts index 7586d506d..343f12d05 100644 --- a/lib/cmds/space_cmds/import.ts +++ b/lib/cmds/space_cmds/import.ts @@ -99,13 +99,13 @@ export const builder = (yargs: Argv) => { }) .option('upload-assets', { describe: - 'Upload local asset files downloaded via the --downloadAssets option of the export. Requires `assetsDirectory`', + 'Upload local asset files downloaded via the --download-assets option of `contentful space export`. Requires `--assets-directory`', type: 'boolean', default: false }) .option('assets-directory', { describe: - 'Path to a directory with an asset export made using the --downloadAssets option of the export. Requires `uploadAssets`', + 'Path to a directory with an asset export made using the --download-assets option of `contentful space export`. Requires `--upload-assets`', type: 'string' }) .config( diff --git a/test/integration/cmds/space/__snapshots__/import.test.js.snap b/test/integration/cmds/space/__snapshots__/import.test.js.snap index 46897153f..c97ebb4be 100644 --- a/test/integration/cmds/space/__snapshots__/import.test.js.snap +++ b/test/integration/cmds/space/__snapshots__/import.test.js.snap @@ -31,11 +31,12 @@ Options: [number] [default: 10] --header, -H Pass an additional HTTP Header [string] --upload-assets Upload local asset files downloaded via the - --downloadAssets option of the export. Requires - \`assetsDirectory\` [boolean] [default: false] + --download-assets option of `contentful space + export`. Requires `--assets-directory` [boolean] + [default: false] --assets-directory Path to a directory with an asset export made using - the --downloadAssets option of the export. Requires - \`uploadAssets\` [string] + the --download-assets option of `contentful space + export`. Requires `--upload-assets` [string] --config An optional configuration JSON file containing all the options for a single run @@ -74,11 +75,12 @@ Options: [number] [default: 10] --header, -H Pass an additional HTTP Header [string] --upload-assets Upload local asset files downloaded via the - --downloadAssets option of the export. Requires - \`assetsDirectory\` [boolean] [default: false] + --download-assets option of `contentful space + export`. Requires `--assets-directory` [boolean] + [default: false] --assets-directory Path to a directory with an asset export made using - the --downloadAssets option of the export. Requires - \`uploadAssets\` [string] + the --download-assets option of `contentful space + export`. Requires `--upload-assets` [string] --config An optional configuration JSON file containing all the options for a single run From 5da6df93acde30c90f37e3a447e5bc61bef5907e Mon Sep 17 00:00:00 2001 From: Michael Pham Date: Fri, 28 Aug 2026 10:38:09 -0500 Subject: [PATCH 2/4] test: correct import help snapshot [AIS-179] --- .../cmds/space/__snapshots__/import.test.js.snap | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/test/integration/cmds/space/__snapshots__/import.test.js.snap b/test/integration/cmds/space/__snapshots__/import.test.js.snap index 1b8047ac6..42a94c928 100644 --- a/test/integration/cmds/space/__snapshots__/import.test.js.snap +++ b/test/integration/cmds/space/__snapshots__/import.test.js.snap @@ -51,8 +51,7 @@ Options: --assets-directory Path to a directory with an asset export made using the --download-assets option of `contentful space export`. Requires - `--upload-assets` - [string] + `--upload-assets` [string] --config An optional configuration JSON file containing all the options for a single run @@ -112,8 +111,7 @@ Options: --assets-directory Path to a directory with an asset export made using the --download-assets option of `contentful space export`. Requires - `--upload-assets` - [string] + `--upload-assets` [string] --config An optional configuration JSON file containing all the options for a single run From a45c3a81668ea029b3652193230b8b3ba41d8de9 Mon Sep 17 00:00:00 2001 From: Michael Pham Date: Fri, 28 Aug 2026 10:45:50 -0500 Subject: [PATCH 3/4] test: escape help snapshot backticks [AIS-179] --- .../cmds/space/__snapshots__/import.test.js.snap | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test/integration/cmds/space/__snapshots__/import.test.js.snap b/test/integration/cmds/space/__snapshots__/import.test.js.snap index 42a94c928..ab1bb2e09 100644 --- a/test/integration/cmds/space/__snapshots__/import.test.js.snap +++ b/test/integration/cmds/space/__snapshots__/import.test.js.snap @@ -45,13 +45,13 @@ Options: --header, -H Pass an additional HTTP Header [string] --upload-assets Upload local asset files downloaded via the --download-assets option of - `contentful space export`. Requires - `--assets-directory` + \`contentful space export\`. Requires + \`--assets-directory\` [boolean] [default: false] --assets-directory Path to a directory with an asset export made using the --download-assets option of - `contentful space export`. Requires - `--upload-assets` [string] + \`contentful space export\`. Requires + \`--upload-assets\` [string] --config An optional configuration JSON file containing all the options for a single run @@ -105,13 +105,13 @@ Options: --header, -H Pass an additional HTTP Header [string] --upload-assets Upload local asset files downloaded via the --download-assets option of - `contentful space export`. Requires - `--assets-directory` + \`contentful space export\`. Requires + \`--assets-directory\` [boolean] [default: false] --assets-directory Path to a directory with an asset export made using the --download-assets option of - `contentful space export`. Requires - `--upload-assets` [string] + \`contentful space export\`. Requires + \`--upload-assets\` [string] --config An optional configuration JSON file containing all the options for a single run From e7c0239e56036c48ab7f3604dc31acb809ff0eb5 Mon Sep 17 00:00:00 2001 From: Michael Pham Date: Fri, 28 Aug 2026 15:19:03 -0500 Subject: [PATCH 4/4] fix: align importer guardrail dependency [AIS-179] --- package-lock.json | 20 ++++++++++---------- package.json | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/package-lock.json b/package-lock.json index e85a6df5b..81ede2579 100644 --- a/package-lock.json +++ b/package-lock.json @@ -21,7 +21,7 @@ "contentful-batch-libs": "^11.0.0", "contentful-collection": "^0.0.4", "contentful-export": "^8.2.0", - "contentful-import": "^10.1.2", + "contentful-import": "^10.2.2", "contentful-management": "^12.13.0", "contentful-migration": "^5.0.0", "emojic": "^1.1.11", @@ -8241,9 +8241,9 @@ } }, "node_modules/contentful-import": { - "version": "10.1.2", - "resolved": "https://registry.npmjs.org/contentful-import/-/contentful-import-10.1.2.tgz", - "integrity": "sha512-65xK7L/jSgqbsDQUVYZVA86cI87X4eCR2xnC1l8R1sozeDPr2NkzVFyY4g2SQv36rucHe5O2HTLtBiOInS9IBg==", + "version": "10.2.2", + "resolved": "https://registry.npmjs.org/contentful-import/-/contentful-import-10.2.2.tgz", + "integrity": "sha512-oXA3AiPea7B3e2H+oCN2H/Hp4usRfxx8Ksm/CsMEWTSJDIdSBrjXl9KF033ZScHPtl5Qv7A7UK+KDK/D/7NVzA==", "license": "MIT", "dependencies": { "@discoveryjs/json-ext": "^0.6.3", @@ -8251,12 +8251,12 @@ "cli-table3": "^0.6.5", "contentful-batch-libs": "^9.7.0", "contentful-management": "^12.13.0", - "date-fns": "^2.30.0", + "date-fns": "^4.4.0", "joi": "^18.2.3", "listr": "^0.14.3", "listr-update-renderer": "^0.5.0", "listr-verbose-renderer": "^0.6.0", - "lodash": "^4.18.1", + "lodash-es": "^4.18.1", "p-queue": "^6.6.2", "yargs": "^17.7.3" }, @@ -9012,9 +9012,10 @@ } }, "node_modules/date-fns": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.1.0.tgz", - "integrity": "sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==", + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.4.0.tgz", + "integrity": "sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==", + "license": "MIT", "funding": { "type": "github", "url": "https://github.com/sponsors/kossnocorp" @@ -15174,7 +15175,6 @@ "version": "4.18.1", "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.18.1.tgz", "integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==", - "dev": true, "license": "MIT" }, "node_modules/lodash.capitalize": { diff --git a/package.json b/package.json index e77411c62..9a9b3d9a6 100644 --- a/package.json +++ b/package.json @@ -92,7 +92,7 @@ "contentful-batch-libs": "^11.0.0", "contentful-collection": "^0.0.4", "contentful-export": "^8.2.0", - "contentful-import": "^10.1.2", + "contentful-import": "^10.2.2", "contentful-management": "^12.13.0", "contentful-migration": "^5.0.0", "emojic": "^1.1.11",