[docs]: Clarify astro:env/server variable evaluation and secret handling

[fkatsuhiro]

Description (required)

Added documentation regarding secret server variable validation during the build process.
Since astro:env/server is evaluated on import, builds can fail if secrets are missing. This PR adds a section explaining this behavior and how to fix it using dummy values.

Related issues & labels (optional)

• Closes astro:env secrets may throw on static pages #12581
• Suggested label: improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	e0ffd59
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6931a1efbbfe110008536fbd
😎 Deploy Preview	https://deploy-preview-12818--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/environment-variables.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[sarah11918]

Hi @fkatsuhiro. Thank you for grabbing the issue and helping us fix it! Your contribution is well-written and easy to read, but I don't think this information belongs in a "caution" block.

We try to use as few notes (and especially cautions!) in docs as possible. If everything is a big note to call your attention, then nothing stands out! 😄 (And, it gives us more room to add things like examples, since your proposal mentions there is a way to address the problem, but doesn't show an example of how to do it!)

Instead, when we are simply describing "how something works", it should be in regular paragraph text. Sometimes this means a new section heading so that specific information about a subtopic is easy to find and link to. And sometimes, new information is not just "one new paragraph" or section, but means reading the whole section and seeing if this information is well presented when the topic is explained. It involves figuring out how to update existing text to make sure the necessary information is presented in the appropriate place, at the appropriate time.

So, how would you propose we update docs if you were not allowed to use any kind of note/caution? Could you try again without doing so?

[fkatsuhiro]

Hi @fkatsuhiro. Thank you for grabbing the issue and helping us fix it! Your contribution is well-written and easy to read, but I don't think this information belongs in a "caution" block.

We try to use as few notes (and especially cautions!) in docs as possible. If everything is a big note to call your attention, then nothing stands out! 😄 (And, it gives us more room to add things like examples, since your proposal mentions there is a way to address the problem, but doesn't show and example of how to do it!)

Instead, when we are simply describing "how something works", it should be in regular paragraph text. Sometimes this means a new section heading so that specific information about a subtopic is easy to find and link to. And sometimes, new information is not just "one new paragraph" or section, but means reading the whole section and seeing if this information is well presented when the topic is explained. It involves figuring out how to update existing text to make sure the necessary information is presented in the appropriate place, at the appropriate time.

So, how would you propose we update docs if you were not allowed to use any kind of note/caution? Could you try again without doing so?

Thank you for your reply !
Sure, I will try this again.

[fkatsuhiro]

@sarah11918 san
Thanks for the feedback! I've updated this PR.

1. Removed the caution block and added a new section "Secrets during the build".
2. Add a sample commands.

Could you take another look when you have time?

[sarah11918]

Thank you, I absolutely will take a look! 🙌

But, please remove all the translations and only submit changes to docs in English. We have a translation procedure for handling the other languages.

[sarah11918]

@florian-lefebvre Can you review the content and placement here?

One thing I noticed is that earlier on the page we say this ("only validated at runtime"), which seems to contradict the content here (unless there is a further nuance not expressed)? Can you provide clarity?

[fkatsuhiro]

Thank you, I absolutely will take a look! 🙌

But, please remove all the translations and only submit changes to docs in English. We have a translation procedure for handling the other languages.

Thank you for letting me know about the translation procedure!
I've removed all the non-English changes and kept only the English docs.

[florian-lefebvre]

Mmmh tricky. I suppose it depends what we mean by runtime. When I wrote this, I think I meant "when it is imported" (VS when you enable validateSecrets, which happens earlier in a vite plugin).

So I'm not sure a new heading is necessary, adding it below the "secret server variables" bullet point might make more sense (and then we can discuss editing the content to fit better). Wdyt Sarah?

[fkatsuhiro]

Thanks for your suggestion!
That makes sense to keep it contextually closer. I'll wait for Sarah's input, and if you both agree, I'll update the PR to move the content inside the bullet point.

[florian-lefebvre]

T&D ftw!

[Fryuni]

We were there when the secrets were discussed... At T&D!!!

[JusticeMatthew]

I struggled to understand in Talking & Docing, but I was there

[sarah11918]

We looked at this one in painful detail on Talking and Doc'ing because we thought we could work this in to our explanation of how secret server variables work. I think we did it!