chore(docs): add branching secrets managements docs (#36306)

* chore(docs): add branching secrets managements docs

* chore: lint

apps/docs/content/guides/deployment/branching.mdx

@@ -567,13 +567,105 @@ All standard configuration options are available in the `[remotes]` block. This
 
 You can use this to maintain different configurations for different environments while keeping them all in version control.
 
+### Managing secrets for branches
+
+For sensitive configuration like SMTP credentials or API keys, you can use the Supabase CLI to manage secrets for your branches. This is especially useful for custom SMTP setup or other services that require secure credentials.
+
+To set secrets for a persistent branch:
+
+```bash
+# Set secrets from a .env file
+supabase secrets set --env-file ./supabase/.env
+
+# Or set individual secrets
+supabase secrets set SMTP_HOST=smtp.example.com
+supabase secrets set SMTP_USER=your-username
+supabase secrets set SMTP_PASSWORD=your-password
+```
+
+These secrets will be available to your branch's services and can be used in your configuration. For example, in your `config.toml`:
+
+```toml
+[auth.smtp]
+host = "env(SMTP_HOST)"
+user = "env(SMTP_USER)"
+password = "env(SMTP_PASSWORD)"
+```
+
+<Admonition type="note" label="Secrets are branch-specific">
+  Secrets set for one branch are not automatically available in other branches. You'll need to set
+  them separately for each branch that needs them.
+</Admonition>
+
+#### Using dotenvx for git-based workflow
+
+For managing environment variables across different branches, you can use [dotenvx](https://dotenvx.com/) to securely manage your configurations. This approach is particularly useful for teams working with Git branches and preview deployments.
+
+##### Environment file structure
+
+Following the conventions used in the [example repository](https://github.com/supabase/supabase/blob/master/examples/slack-clone/nextjs-slack-clone-dotenvx/README.md), environments are configured using dotenv files in the `supabase` directory:
+
+| File            | Environment | `.gitignore` it? | Encrypted |
+| --------------- | ----------- | ---------------- | --------- |
+| .env.keys       | All         | Yes              | No        |
+| .env.local      | Local       | Yes              | No        |
+| .env.production | Production  | No               | Yes       |
+| .env.preview    | Branches    | No               | Yes       |
+| .env            | Any         | Maybe            | Yes       |
+
+##### Setting up encrypted secrets
+
+1. Generate key pair and encrypt your secrets:
+
+```bash
+npx @dotenvx/dotenvx set SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET "<your-secret>" -f supabase/.env.preview
+```
+
+This creates a new encryption key in `supabase/.env.preview` and a new decryption key in `supabase/.env.keys`.
+
+2. Update project secrets:
+
+```bash
+npx supabase secrets set --env-file supabase/.env.keys
+```
+
+3. Choose your configuration approach in `config.toml`:
+
+Option A: Use encrypted values directly:
+
+```toml
+[auth.external.github]
+enabled = true
+secret = "encrypted:<encrypted-value>"
+```
+
+Option B: Use environment variables:
+
+```toml
+[auth.external.github]
+enabled = true
+client_id = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_CLIENT_ID)"
+secret = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET)"
+```
+
+<Admonition type="note" label="Secret fields">
+  The `encrypted:` syntax only works for designated "secret" fields in the configuration (like
+  `secret` in auth providers). Using encrypted values in other fields will not be automatically
+  decrypted and may cause issues. For non-secret fields, use environment variables with the `env()`
+  syntax instead.
+</Admonition>
+
+##### Using with preview branches
+
+When you commit your `.env.preview` file with encrypted values, the branching executor will automatically retrieve and use these values when deploying your branch. This allows you to maintain different configurations for different branches while keeping sensitive information secure.
+
 ### Rolling back migrations
 
 You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.
 
-To fix this, push your latest changes, then delete the preview branch in Supabase and reopen it.
+To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.
 
-The new preview branch is reseeded from your `./supabase/seed.sql` file by default. Any additional data changes you made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.
+The new preview branch is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.
 
 ### Seeding behavior
 

supa-mdx-lint/Rule003Spelling.toml

@@ -138,6 +138,7 @@ allow_list = [
     "DigitalOcean",
     "Django",
     "Docker",
+    "dotenvx",
     "Drizzle",
     "ElevenLabs",
     "EnterpriseDB",