From de3b9a158b2840fd53eeca61e1fab20fba84e752 Mon Sep 17 00:00:00 2001
From: Iss <74388823+isshaddad@users.noreply.github.com>
Date: Mon, 20 Apr 2026 13:19:33 -0400
Subject: [PATCH] docs: document secret env vars and Vercel sync behavior
 (#3419)

---
 docs/deploy-environment-variables.mdx | 9 +++++++++
 docs/vercel-integration.mdx           | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/docs/deploy-environment-variables.mdx b/docs/deploy-environment-variables.mdx
index a4c3b75da..529c621de 100644
--- a/docs/deploy-environment-variables.mdx
+++ b/docs/deploy-environment-variables.mdx
@@ -30,6 +30,15 @@ We deploy your tasks and scale them up and down when they are triggered. So any
   locally.
 </Note>
 
+### Secret environment variables
+
+When creating an environment variable, you can mark it as a **Secret**. Secret values are hidden in the dashboard and cannot be viewed after creation.
+
+<Warning>
+  Marking a variable as a Secret is irreversible and can only be done when creating the variable. To
+  change this setting, you must delete the variable and create a new one.
+</Warning>
+
 ### Editing environment variables
 
 You can edit an environment variable's values. You cannot edit the key name, you must delete and create a new one.
diff --git a/docs/vercel-integration.mdx b/docs/vercel-integration.mdx
index a465f5aa3..3c2cc1b96 100644
--- a/docs/vercel-integration.mdx
+++ b/docs/vercel-integration.mdx
@@ -104,6 +104,12 @@ The following variables are excluded from the Vercel → Trigger.dev sync:
 
 You can control sync behavior per-variable from your project's Vercel settings. Deselecting a variable prevents its value from being updated during future syncs.
 
+<Note>
+  Environment variables are pulled from Vercel before each build. To sync updated values into
+  Trigger.dev, trigger a new Vercel deployment — either by pushing a commit to your connected branch
+  or by redeploying from the Vercel dashboard.
+</Note>
+
 <Warning>
   If you are experiencing incorrectly populated environment variables, check that you are not using
   the `syncVercelEnvVars` build extension in your `trigger.config.ts`. This extension is deprecated