docs: improve env var documentation with .env upload + ctx environmen…

[lindseystead]

docs: improve env var documentation with .env upload + ctx environment details

Closes #1248

✅ Checklist

• I have followed every step in the contributing guide
• The PR title follows the convention.
• I ran and tested the code works

---

Summary

This PR addresses issue #1248 by adding two missing documentation sections to the environment variables guide:

1. Initial load from .env file: Documents how to use envvars.upload() to initially load environment variables from a .env file into Trigger.dev cloud environment. This was previously undocumented.

2. Getting the current environment: Documents how to access the current environment information (ctx.environment.slug, ctx.environment.type, etc.) when using envvars.retrieve(), which previously had no direct way to determine the current environment.

---

Testing

• Verified the documentation renders correctly in the docs site
• Checked that code examples are syntactically correct
• Confirmed the sections are properly placed in the documentation structure

---

Changelog

• Added "Initial load from .env file" section with examples for both outside and inside task contexts
• Added "Getting the current environment" section explaining how to use ctx.environment to access environment information
• Both sections include code examples and links to related documentation

---

Screenshots

N/A - Documentation only change

[changeset-bot]

⚠️ No Changeset found

Latest commit: 997c183

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

This pull request updates the deployment environment variables documentation file by adding sections that explain how to perform initial environment variable loading using envvars.upload() with code examples for both project-scoped and task-scoped usage. It also documents how to retrieve current environment information within a task via the context object (ctx.environment, ctx.project.ref), including clarification on what each property provides, and introduces a contrasting note between envvars.upload() and syncEnvVars.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10–15 minutes

• Verify accuracy of envvars.upload() API usage and behavior descriptions in both project-scoped and task-scoped contexts
• Confirm correctness of context object property access examples (ctx.environment.slug, ctx.environment.type, ctx.environment.id, ctx.project.ref)
• Validate the distinction and contrast drawn between envvars.upload() and syncEnvVars
• Ensure code examples are executable and follow project documentation conventions

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: adding documentation for .env file upload and context environment details in the env var guide.
Description check	✅ Passed	The description follows the template structure with all required sections completed: issue link, checklist, summary, testing details, changelog, and screenshots note.
Linked Issues check	✅ Passed	The PR fully addresses both requirements from issue #1248: documents envvars.upload() for initial .env loading and explains how to access current environment via ctx.environment.
Out of Scope Changes check	✅ Passed	All changes are documentation updates directly addressing the two objectives from issue #1248, with no unrelated code modifications present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/deploy-environment-variables.mdx (1)

132-162: Expand property reference to include additional available context properties.

The documented properties are accurate and the type values are correct and exhaustive. However, the documentation omits several available properties that would benefit users:

• ctx.environment.branchName — Present when type === "PREVIEW" (useful for preview environment workflows)
• ctx.project.id, ctx.project.slug, ctx.project.name — Available alongside the documented ctx.project.ref

Consider adding these properties to the reference list to provide users with the complete context API surface.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 892bed8 and 997c183.

📒 Files selected for processing (1)

• docs/deploy-environment-variables.mdx (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: julienvanbeveren
Repo: triggerdotdev/trigger.dev PR: 2417
File: apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.import.ts:56-61
Timestamp: 2025-08-19T09:49:07.011Z
Learning: In the Trigger.dev codebase, environment variables should default to `isSecret: false` when not explicitly marked as secrets in the syncEnvVars functionality. This is the intended behavior for both regular variables and parent variables.

📚 Learning: 2025-08-19T09:49:07.011Z

Learnt from: julienvanbeveren
Repo: triggerdotdev/trigger.dev PR: 2417
File: apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.import.ts:56-61
Timestamp: 2025-08-19T09:49:07.011Z
Learning: In the Trigger.dev codebase, environment variables should default to `isSecret: false` when not explicitly marked as secrets in the syncEnvVars functionality. This is the intended behavior for both regular variables and parent variables.

Applied to files:

• docs/deploy-environment-variables.mdx

🔇 Additional comments (1)

docs/deploy-environment-variables.mdx (1)

86-130: ---

Example 2 in the "task context" section contains incorrect API usage and must be corrected.

The actual envvars.upload() API requires both projectRef and env parameters as mandatory arguments, not optional context-inferred values. The documentation at lines 108-126 incorrectly shows calling envvars.upload() with only the options object:

// INCORRECT - shown in docs
await envvars.upload({
  variables: parsed,
  override: false,
});

This should be corrected to include the required parameters:

// CORRECT
await envvars.upload("proj_your_project_ref", "prod", {
  variables: parsed,
  override: false,
});

Remove the misleading comment about automatic context inference, as the API signature requires explicit projectRef and env arguments.

⛔ Skipped due to learnings

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 2155
File: hosting/docker/.env.example:4-7
Timestamp: 2025-06-06T23:55:01.933Z
Learning: In the trigger.dev project, .env.example files should contain actual example secret values rather than placeholders, as these help users understand the expected format. The files include clear warnings about not using these defaults in production and instructions for generating proper secrets.

Learnt from: julienvanbeveren
Repo: triggerdotdev/trigger.dev PR: 2417
File: apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.import.ts:56-61
Timestamp: 2025-08-19T09:49:07.011Z
Learning: In the Trigger.dev codebase, environment variables should default to `isSecret: false` when not explicitly marked as secrets in the syncEnvVars functionality. This is the intended behavior for both regular variables and parent variables.