Add a managing secrets guide

[devin-ai-integration]

Summary

New guide at guides/managing-secrets documenting the pattern we use in the Ravion monorepo's own ravion.yaml: one Secrets Manager secret per environment holding a JSON object of many keys, with each module referencing individual keys via the ARN's JSON-key suffix.

secrets:
  - name: DATABASE_URL
    valueFrom: "arn:aws:secretsmanager:us-east-2:111122223333:secret:prod/myapp-AbCdEf:DATABASE_URL::"

Opens with a <Note> that native secret management in Ravion is coming soon, matching how the custom-domains guide frames its own gap.

Beyond the recommendation, it covers the things that actually bite people, verified against the module definitions and terraform rather than inferred:

• The trailing :: is required when a JSON key is present; dropping the key entirely injects the whole secret string.
• ECS resolves secrets at task start, so a rotation needs a redeploy; put-secret-value replaces the whole document, so adding a key means a merge.
• The generated execution role policy allows Secrets Manager / SSM / KMS access conditioned on the same AWS account, so cross-account references fail; customer-managed KMS keys additionally need the key policy to allow the execution role; a user-supplied execution_role_arn bypasses the generated policy entirely.
• Build-time secrets go through build_environment_variables with fromSecretManager / fromParameterStore, plus the dockerfile_inject_env_variables build-arg caveat.
• Parameter Store as the alternative and when it stops being the better choice.

The guide deliberately does not enumerate per-module secret behavior or the secrets each module creates — that would go stale against the catalog. It points at the module catalog pages and stack outputs instead.

Also registers the page in docs.json, links it from the "Managing environment variables through Ravion" gap in the Flightcontrol migration guide, and adds four technical terms to the Vale vocabulary.

Link to Devin session: https://app.devin.ai/sessions/851b7a82769844afad6491e5e44d9efa
Requested by: @flybayer

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Ravion	🟢 Ready	View Preview	Aug 4, 2026, 6:54 PM

[mabadir]

This line doesn't make sense in this section in docs.

[devin-ai-integration]

Agreed — sharing a value across services works with per-value secrets too, so it isn't an argument for the one-secret pattern. Removed the bullet.

[mabadir]

This also helps with rotation

[devin-ai-integration]

Added: AWS rotates those secrets in place without touching your environment secret, which is another reason to leave them where they are.

[mabadir]

This is anti the recommendation to call the secret with /env/app.

[devin-ai-integration]

Good catch — it undercut the <env>/<app> naming right above it. Flipped it to say keep the environment in the name even when each environment has its own account, so the ARN identifies its environment on sight in config diffs, task definitions, and IAM policies.