fix Vercel warnings - `the following environment variables are set on your Vercel project, but missing from "turbo.json". These variables WILL NOT be available to your application and may cause your build to fail.`

[dimaMachina]

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 8f19e5aeb2f5aab813d0f3fc9aef30a429b2e17a

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

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Ready	Preview	Comment	Nov 20, 2025 6:31pm
agents-manage-api	Ready	Preview	Comment	Nov 20, 2025 6:31pm
agents-manage-ui	Ready	Preview	Comment	Nov 20, 2025 6:31pm
agents-run-api	Ready	Preview	Comment	Nov 20, 2025 6:31pm

[claude[bot]]

Claude finished @dimaMachina's task —— View job

---

Code Review Analysis Complete

Todo List:

• [x] Read and analyze the turbo.json changes
• [x] View the Vercel warning image to understand the problem
• [x] Understand the repository structure and existing patterns
• [x] Evaluate the solution approach and completeness
• [x] Provide comprehensive review feedback covering all architectural dimensions
• [x] Post final review with recommendations

---

Code Review: Vercel Environment Variables Fix

Context Summary

This PR addresses Vercel deployment warnings where environment variables configured in the Vercel project were missing from turbo.json's globalEnv array. The warning indicated that these variables would not be available to the application during build, potentially causing deployment failures.

Changes Analysis

File: turbo.json:5-26

• Added 10 environment variables to the globalEnv array:
  • INKEEP_AGENTS_MANAGE_API_URL
  • INKEEP_AGENTS_RUN_API_URL
  • INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET
  • INKEEP_AGENTS_RUN_API_BYPASS_SECRET
  • NANGO_SECRET_KEY
  • SIGNOZ_URL
  • SIGNOZ_API_KEY
  • TENANT_ID
  • NANGO_SERVER_URL
  • NANGO_CONNECT_BASE_URL

Technical Assessment

✅ Strengths

1. Direct Problem Resolution: Correctly addresses the specific Vercel warning by adding missing environment variables
2. Proper Turbo Configuration: Uses the standard globalEnv array approach for Turbo to track environment variables across the monorepo
3. Clear Intent: The changes directly match the variables shown in the Vercel warning image

⚠️ Areas for Consideration

1. Security & Secrets Management

Severity: High

• Concern: Several variables contain "SECRET" or "KEY" in their names (INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET, NANGO_SECRET_KEY, SIGNOZ_API_KEY)
• Risk: While adding them to globalEnv is necessary for build availability, this makes them visible to all tasks in the monorepo
• Recommendation:
  • Consider if all secrets truly need global availability or if they could be scoped to specific tasks using the env property on individual tasks
  • Document which applications/packages actually need each secret
  • Ensure proper secret rotation practices are in place

2. Configuration Completeness

Severity: Medium

• Gap Analysis: The PR only addresses variables that triggered warnings, but doesn't validate if ALL environment variables used by the applications are properly declared
• Recommendation: Audit each application's environment variable usage to ensure comprehensive coverage:

  # Suggested validation approach
  grep -r "process\.env\." --include="*.ts" --include="*.js" . | grep -v node_modules
  

3. Documentation & Governance

Severity: Medium

• Missing Context: No documentation about what each variable does or which applications require them
• Recommendation:
  • Add inline comments in turbo.json explaining variable purposes
  • Create/update environment variable documentation
  • Consider a validation script that ensures Vercel project variables match turbo.json

4. Environment Variable Categorization

Severity: Low-Medium

• Observation: Mixed categorization of variables (API URLs, secrets, tenant config, monitoring)
• Suggestion: Consider grouping with comments for better maintainability:

  "globalEnv": [
    // Build & Infrastructure
    "NODE_ENV", "CI", "ENVIRONMENT",
  
    // Turbo
    "TURBO_TOKEN", "TURBO_TEAM", "TURBO_TELEMETRY_DISABLED",
  
    // Database
    "DATABASE_URL",
  
    // API Configuration
    "INKEEP_AGENTS_MANAGE_API_URL",
    "INKEEP_AGENTS_RUN_API_URL",
  
    // Secrets (consider task-specific scoping)
    "ANTHROPIC_API_KEY",
    "OPENAI_API_KEY",
    // ...
  ]
  

System Architecture Considerations

Monorepo Environment Management

• Pattern Consistency: This follows established patterns in the codebase for global environment management
• Scalability: Current approach scales well but consider future governance as the variable count grows
• Alternative Approach: For highly sensitive variables, consider task-specific env declarations rather than global exposure

Deployment Strategy Alignment

• Vercel Integration: Solution correctly integrates with Vercel's environment variable system
• Multi-App Deployment: Properly supports the monorepo's multiple Vercel deployments (agents-docs, agents-manage-ui, agents-run-api, agents-manage-api)

Recommendations

Immediate Actions

1. Verify Completeness: Ensure all environment variables used by applications are included
2. Security Review: Audit if all secrets truly need global scope or can be task-specific

Follow-up Improvements

1. Documentation: Create comprehensive environment variable documentation
2. Validation Automation: Add a script/CI check to validate Vercel project vars match turbo.json
3. Security Enhancement: Consider using task-specific env for highly sensitive variables

Consider for Future

• Environment variable validation in CI/CD
• Automated synchronization between Vercel project settings and turbo.json
• Standardized naming conventions for new environment variables

Verdict

✅ Approve with Follow-up: The PR correctly solves the immediate Vercel deployment warnings. The solution is technically sound and follows established patterns. However, I recommend addressing the security and documentation concerns in follow-up work to maintain good practices as the system scales.

---