feat: forward agent runner ids on deploy creation

[aitchiss]

🎉 Thanks for submitting a pull request! 🎉

Summary

Second part of PAW-210 — the netlify-cli slice of the recommended approach. Follows netlify/agent-runner-orchestrator#1125.

Today the runner↔deploy link is made at deploy completion, so an agent runner just stays running through the whole build and bitballoon can't distinguish "the agent is thinking" from "the agent is done, the preview is building". The fix is to link at deploy creation instead, which means the runner ids have to reach the createSiteDeploy request.

The orchestrator now sets NETLIFY_AGENT_RUNNER_ID and NETLIFY_AGENT_RUNNER_SESSION_ID in the CLI's env next to the existing NETLIFY_DEPLOY_SOURCE. This PR forwards them through as fields on the create-deploy body. One-field passthrough; no change to the deploy flow.

What changed

• src/utils/deploy/deploy-source.ts (new) — getDeploySourceFields() returns deploy_source plus agent_runner_id / agent_runner_session_id. Each id is omitted when unset rather than sent as undefined.
• src/commands/deploy/deploy.ts — both createSiteDeploy call sites spread that helper in place of the duplicated deploy_source line:
  • runDeploy (~L604), which creates the deploy on the --no-build path
  • deploy (~L1394), which creates it up front when building

Reviewer notes

• Both create paths are covered, and they're the only ones. Those two call sites were the only places the CLI sent deploy_source. --trigger goes through createSiteBuild (a git-based build trigger) and anonymous/drop deploys never sent a deploy source, so neither is in scope.
• Deploy retries need nothing here. The orchestrator's retry path re-invokes the CLI, so the env is re-read on each createSiteDeploy.
• The session id is included as well as the runner id. The orchestrator sets both, and the bitballoon slice needs the session to point at the deploy (session.deploy_id). Happy to trim to just agent_runner_id if you'd rather the CLI carried only the one field.
• Unrecognised ids: as flagged on the orchestrator PR, bin-local.ts generates local-<hex> ids for local runs, so bitballoon's create path should ignore an id it doesn't recognise rather than erroring.
• Test results: new unit tests 5/5; full unit suite 477/477 across 66 files (the 5 reported "errors" are unhandled telemetry rejections from geo-location/exec-fetcher hitting a 500 on a binary download — pre-existing and environmental). Full deploy integration suite 55/55, including two new tests covering both create paths. typecheck, lint and format:check all clean.

Still to come on PAW-210

• bitballoon: accept the params in Api::V1::DeploysController#create, link at creation in Deploy.create_with_site!, and add the derived preview_state to the agent runner snapshot serializer.

---

For us to review and ship your PR efficiently, please perform the following steps:

• Open a bug/issue before writing your code 🧑‍💻 — tracked in PAW-210.
• Read the contribution guidelines 📖
• Update or add tests (if any source code was changed or added) 🧪
• Update or add documentation (if features were changed or added) 📝 — n/a, these are internal env vars set by the orchestrator and aren't part of the documented CLI surface (NETLIFY_DEPLOY_SOURCE isn't documented either).
• Make sure the status checks below are successful ✅

A picture of a cute animal (not mandatory, but encouraged)

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dbebadac-8d9f-4c8f-a872-4fb7e58fac41

📥 Commits

Reviewing files that changed from the base of the PR and between 88ece29 and 2179d65.

📒 Files selected for processing (5)

• src/commands/deploy/deploy.ts
• src/utils/deploy/deploy-source.ts
• tests/integration/commands/deploy/deploy-api-routes.ts
• tests/integration/commands/deploy/deploy.test.ts
• tests/unit/utils/deploy/deploy-source.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• netlify/blueprints (manual)

Included review availability: 6 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

---

📝 Walkthrough

Summary by CodeRabbit

• Improvements

  • Deployment metadata now consistently includes the deployment source.
  • Agent runner identifiers are forwarded when available, for both build and no-build deployments.
  • Missing or empty metadata is omitted automatically.

• Tests

  • Added coverage for deployment metadata across build modes, configured sources, and optional agent runner details.

Walkthrough

The change adds getDeploySourceFields() to centralize deploy metadata generation. The helper defaults deploy_source to cli and conditionally includes agent-runner identifiers. Both build and no-build deployment requests use the helper. Unit tests cover environment handling, and integration tests verify request payloads for both deployment flows.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 2179d

This PR forwards optional agent runner identifiers when creating deploys without changing the deploy flow; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: ndhoule

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: forwarding agent runner IDs during deploy creation.
Description check	✅ Passed	The description accurately explains the deploy-source helper, both creation paths, tests, and the purpose of forwarding runner identifiers.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/paw-210-cli-b7febc

---

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

[github-actions]

📊 Benchmark results

Comparing with 88ece29

• Dependency count: 1,121 (no change)
• Package size: 432 MB ⬆️ 0.00% increase vs. 88ece29
• Number of ts-expect-error directives: 346 (no change)

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/netlify-cli@8436

commit: 2179d65

[whitep4nth3r]

Started going through this with @aitchiss - best course of action before this can be tested thoroughly is to get the linked bitballoon PR merged!

[aitchiss]

I was able to verify this E2E on the pre-release - screenshot of deploy linked to agent runner id passed in env vars: