Add a clarification/note on the proper formatting of the contents of .magento.env.yaml

[ak77-prime]

Is there an existing issue for this?

• [X] I have searched the existing issues

Which topic?

https://devdocs.magento.com/cloud/project/magento-env-yaml.html

What's wrong with the content?

Customers are sometimes configuring .magento.env.yaml incorrectly due to/evidenced by the following issues

1. They are using the wrong indentation - if the indentation is not consistent throughout the file, the settings with the wrong indentation will not be applied (reference Support ticket https://magento.zendesk.com/agent/tickets/538446)
2. Misunderstanding about what "stage" actually refers to 2a. They are repeating the "stage" block/node in their YAML file 2b. They think that "stage" refers to the environment and are using integration or dev, stage, and prod in their YAML file, e.g.,

dev:
  deploy:
...
stage:
  deploy
...
prod:
  deploy:
...

What changes do you propose?

I suppose we could provide a link to the documentation on the proper syntax for the YAML file, e.g., https://quickref.me/yaml

The Introduction section indicates:

[YAML](https://yaml.org/) is a data serialisation language designed to be directly writable and readable by humans

YAML does not allow the use of tabs
Must be space between the element parts
YAML is CASE sensitive

This will help address the first bullet point above

For the second point, add a description about what "stage" deploys to, i.e., it's one of these 3 deployment phases - build, deploy, and post-deploy

https://devdocs.magento.com/cloud/reference/discover-deploy.html#cloud-deploy-over-phases

Anything else that can help to cover this?

[m2-assistant[bot]]

Hi @ak77-prime. Thank you for your report. To speed up processing of this issue, make sure that you provided sufficient information.

Add a comment to assign the issue: @magento I am working on this

---

• Join Magento Community Engineering Slack and ask your questions in #github channel.

[hguthrie]

Thanks for letting us know. Repeating the stage block is definitely a concern and we can improve on our presentation of how this file should be constructed. On the YAML, we can offer some minimal guidance, but as a general rule we try not to link to external references. Thanks for the suggestions, though. It helps us to understand the issues they are having.