[APPS-2792] Add: v3 to v4 migration guide entry

[tyffical]

Motivation

• Local Node execution for App Builder backend functions is landing across several already-merged PRs (in-process execution, npm run dev:verify, the runtime network/subprocess guard, build-time rejection of Node built-ins/raw network globals, Custom Credentials local resolution, and real-identity hydration for getInitiatingUser()/getExecutionUser()), with process.env scoping as the last piece still in review.
• This bundle of changes is breaking for existing apps and is intended to ship as the next major version bump — MIGRATIONS.md needs a ## v3 to v4 entry describing it before that bump goes out.
• This PR can be reviewed and merged now; the actual version bump (bump.yaml dispatch) should wait until the process.env scoping work and its security sign-off land — see Out of Scope below.

Changes

2 changes across MIGRATIONS.md

What changed	File
Added a ## v3 to v4 entry covering in-process local execution, npm run dev:verify, and the process.env allowlist, plus its Table of Contents entry	MIGRATIONS.md
Added subsections covering Custom Credentials local resolution (datadog-app.local.json) and real-identity hydration for getInitiatingUser()/getExecutionUser(), plus their Table of Contents entries	MIGRATIONS.md

QA Instructions

Docs-only change — no functional QA applies.

yarn cli integrity
# Regenerates the file's Table of Contents from its headings and runs the repo's install/format/typecheck/OSS-compliance checks
# Expected: exits 0; `git status --short` shows only MIGRATIONS.md changed ✅ VERIFIED

The described behavior was cross-checked against the actual merged code rather than assumed:

• In-process execution and the /__dd/executeAction vs. /__dd/executeActionViaCloud dev-server routing: packages/plugins/apps/src/vite/dev-server.ts, packages/plugins/apps/src/vite/local-execution.ts
• npm run dev:verify / DEV_VERIFY_MODE routing: packages/plugins/apps/src/constants.ts, packages/plugins/apps/src/vite/dev-server.ts
• Node built-in import / raw network global rejection: gh pr diff 476 --repo DataDog/build-plugins
• process.env allowlist (SAFE_ENV_KEYS = ['PATH', 'HOME', 'NODE_ENV', 'TMPDIR']): read directly off the still-open tiffany.trinh/apps-2792-env-guard-hardening branch's packages/plugins/apps/src/vite/env-guard.ts, since env-guard.ts isn't on master yet
• Custom Credentials local resolution (resolveCustomCredentials, the sanitized JSON-parse error that never echoes file content) and real-identity hydration (RuntimeUser, assertValidRuntimeContext): read directly off packages/plugins/apps/src/vite/custom-credentials-resolver.ts and packages/plugins/apps/src/vite/local-execution.ts
• Confirmed no other customer-facing action beyond what's described by reading the diffs of [APPS-2792] Add: in-process local execution for backend functions #479, [APPS-2792] Add: harden the in-process local execution path #480, [APPS-2792] Add: wire local execution into the real dev server #481, [APPS-2792] Add: reject Node built-in imports in backend files #476, [APPS-2792] Add: runtime network/subprocess guard for local execution #484

Blast Radius

• Documentation-only change (MIGRATIONS.md). Zero runtime risk.

Out of Scope / Follow-ups

1 item deferred

Item	Status	Next step
The actual major version bump (bump.yaml dispatch) this entry documents	blocked	Wait until the process.env scoping (Secret Store parity, #504) and env-guard hardening (#510) work merge and security sign-off completes, then dispatch the bump separately

[tyffical]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-10T06:44:55.346261Z	281ac50	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🟡 Changes recommended

Documentation corrections remain in MIGRATIONS.md.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

MIGRATIONS.md:52

• The phrase “even though the equivalent read against the deployed function succeeds in production” is too broad: an arbitrary shell variable such as the AWS_REGION example is not necessarily configured in the deployed app at all. Qualify this with “when that variable is provided by the deployed app or a connection” so the guide does not imply production supplies every local shell variable.

Reading any other variable — including one your shell has set, or one a secret-backed connection would resolve to in production — returns `undefined` locally, even though the equivalent read against the deployed function succeeds in production. The one exception is a Custom Credentials-backed variable declared in `datadog-app.local.json` (see below).

MIGRATIONS.md:36

• This migration entry omits the other half of the breaking behavior: local execution installs runtime guards for network, subprocess, worker-thread, and DNS-resolver APIs, so a dependency can now fail when it makes one even if the app file has no forbidden syntax. Please document that alongside the build-time checks; literal dynamic Node imports are also rejected, so “static imports” is too narrow.

Static imports of Node built-ins (`fs`, `child_process`, `net`, etc.) and raw network globals (`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`) in a backend file are rejected at build time. Backend functions have never had access to these in production, so this only surfaces earlier — at `npm run dev` time instead of only once the app is published — a case that previously appeared to work locally but would fail in production.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 281ac50508

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".