How to create and configure the .well-known/gpc.json file in Magento 2 Cloud

What is the .well-known/gpc.json file, what is it used for, and how is it created?

The .well-known/gpc.json file, located in the web root directory, informs browsers and privacy tools about your website’s support for Global Privacy Control (GPC).. It contains information about the current status of GPC signal processing (enabled or disabled), version, and the date of the last update.


The extension automatically creates the JSON file during installation. Each time the admin changes the Enabled switcher position in GPC configurations or updates the Last Update Date value in the “GPC .well-known Settings”, the system generates the gpc.json file in the .well-known directory, allowing third-party services to download and read it.

Why doesn’t the file get created and updated automatically on Magento 2 Cloud?

The creation and updating of the .well-known/gpc.json file in Magento Cloud differ from the standard automatic process.

Magento Cloud has limitations related to file system access and editing, which can prevent the automatic creation or updating of this file. This may prevent the module from automatically creating and updating the file. As a result, the file won’t be created, and won’t be available from the frontend. If this occurs, you’ll see corresponding messages in the Magento logs and in the “GPC .well-known Settings” configuration section.

The .well-known/gpc.json file configuration in Magento 2 Cloud

Step 1. gpc.json generation

Option A – via extension in the local dev

This is the simplest way to create the needed file. In a local development environment, it’s enough to set the target extension configurations. After saving configurations, the .well-known/gpc.json file will be automatically updated accordingly.

Option B – manually in the local dev

In the project root, run the command that will create the required folder in the web root and generate the file with the sample structure:

mkdir <web root>/.well-known
cat > <web root>/.well-known/gpc.json << 'EOF'
{
    "gpc": true,
    "version": "1.0",
    "created": "2025-06-24"
}
EOF

In the file content, it is necessary to update the following values to the specific ones:

  • gpc“: true or false, depending on the Enabled switcher condition in the extension configurations
  • version
  • created“: the last update date in YYYY-MM-DD format, for example “2025-06-24”

Step 2. Deploying the changes in production

Ensure that the gpc.json file contains the correct values for the gpc, version, and created keys. Place it in the repository at <web root>/.well-known/gpc.json, commit the changes, and push them to the remote repository. Once the deployment is complete, the gpc.json file will appear on the website and will be available for reading.

Important Notice:

Each time you change the Enabled setting or update the Last Update Date, repeat these steps to regenerate and deploy the updated gpc.json file.

Was this article helpful?