# How to run a runtime upgrade with coding agents > A runtime upgrade starts from a supported target and a passing baseline. Learn how to find every version selector, repair one compatibility class at a time, validate the deployed artifact, and use Factory to run the migration across repositories. URL: https://factory.com/articles/coding-agent-runtime-upgrades Published: 2026-09-24 Updated: 2026-10-23 To run a runtime upgrade safely, pick a supported target line, record a passing baseline, and change every version selector in one mechanical step. Then repair compatibility failures one class at a time and validate the same artifact you deploy. A coding agent can handle the search and the repetitive edits, while the pull request shows every selector changed and every command run. The hard part is compatibility. A repository may pin the runtime in CI, containers, local tooling, deployment configuration, and generated files, while its dependencies rely on APIs that changed between releases. Start from an explicit target. The Node.js project publishes its [release and support status](https://nodejs.org/en/about/previous-releases), including which lines receive long-term maintenance. That schedule is a better input than a request to "use the latest version." ## Find every place the runtime is selected Inventory every place that selects or assumes a runtime before editing anything. Search for native extensions and build tools too, because they may support a narrower range than the application itself. The table lists the usual hiding places and what to check in each one. | Location | What to check | | --- | --- | | Version manager files | The pinned version for local development | | Container images | Base image tag and any build stage images | | CI workflow files | Setup steps and test matrices | | Package metadata | Declared engine or interpreter range | | Lockfiles | Packages resolved for the old runtime | | Deployment manifests | Runtime set by the hosting platform | | Setup guides | Commands new developers copy | Record the current build, test, lint, and packaging results before changing versions. A failing baseline makes later failures ambiguous. Preserve the exact commands and environment needed to reproduce it. ## Make the upgrade incremental Separate mechanical version changes from application repairs when the repository allows it. First update the declared runtime and regenerate the lockfile with the approved package manager. Then run the narrowest failing command and repair one compatibility class at a time. Compiler errors, removed APIs, changed module resolution, and native build failures need different evidence. Capture the first failure, identify the component that owns it, and confirm the upstream migration guidance before editing. Avoid broad dependency refreshes unless the target runtime requires them. Extra upgrades increase the review surface and make regressions harder to attribute. ## Validate in the real environment Run the full repository gate on the new runtime, then build the same artifact used in deployment. Containerized services should rebuild from a clean base image. Libraries should test their supported version range rather than only the newest interpreter. Exercise startup, shutdown, background work, network clients, serialization, and any native modules. These paths can fail after compilation succeeds. Compare logs and warnings with the baseline, and treat new deprecation messages as follow-up work with an owner. The pull request should state the old and new runtime lines, every version selector changed, dependency updates required, commands run, and any unsupported environment. Keep rollback simple by avoiding unrelated refactors. A complete migration leaves one source of truth for each environment. Remove obsolete pins only after consumers have moved, and add a check that reports drift between local development, CI, and deployment. That check keeps the next upgrade from starting with another inventory project. ## How Factory runs runtime upgrades Factory is a platform for running a software factory, where agents called Droids take work from a signal to a reviewed pull request. A runtime upgrade fits that model well because the steps repeat across repositories and each one ends in a reviewable change. The flow below shows where the loop repeats. Validation failures go back to a single compatibility repair rather than a broad rewrite. Target line
supported release from the project schedule"] B["Baseline
build, test, lint, package on the old runtime"] C["Mechanical change
every version selector and the lockfile"] D["Repair one class
removed API, module resolution, native build"] E{"Gate and artifact pass?"} F["Pull request
selectors, commands, remaining gaps"] A --> B --> C --> D --> E E -- no --> D E -- yes --> F `} /> **Durable repository context.** Factory's [AGENTS.md guidance](https://docs.factory.com/harness/agents-md) puts the exact install, test, type check, lint, and build commands in a file committed with the project. Droid reads it before writing code, so it updates the right version declarations without replacing project-specific steps with generic ones. **Coordinated migrations.** For an upgrade across many repositories, Factory [Missions](https://docs.factory.com/missions/overview) start with a plan of features and milestones, then hand execution to an orchestration layer that validates progress as it goes. Keep one pull request per repository so each owner can review and merge on their own schedule. **Review and headless checks.** [Automated code review](https://docs.factory.com/software-factory/code-review-ci) runs on each pull request and posts inline comments. [Droid Exec](https://docs.factory.com/droid-exec/overview) is read-only by default, which makes it a safe way to run the inventory step in CI before any edits are allowed. To start a migration or add review to your pull requests, run these commands in the Droid CLI.
Plan a migration. Breaks multi-repository work into features and milestones. One-time setup. Adds automated code and security review to your pull requests.
## Frequently asked questions ### What is a runtime upgrade? A runtime upgrade moves a codebase to a newer language or framework runtime line, such as a new Node.js release. It touches every place that selects or assumes the runtime, including CI, containers, local tooling, deployment configuration, package metadata, and lockfiles. ### How do you choose the target runtime version? Use the project's published release and support status. The Node.js project, for example, publishes which release lines receive long-term maintenance. That schedule is a better input than a request to use the latest version. ### Why should a runtime upgrade be incremental? Separating the mechanical version change from application repairs keeps each failure attributable. Repair one compatibility class at a time, such as removed APIs, module resolution, or native builds, and avoid dependency refreshes the target runtime does not require. ### How do you validate a runtime upgrade? Run the full repository gate on the new runtime, build the same artifact used in deployment, and exercise startup, shutdown, background work, network clients, serialization, and native modules. Compare logs and warnings with the baseline. ### How does Factory help with runtime upgrades? AGENTS.md keeps the exact build and test commands beside the code, Missions plan and coordinate long-running work with validation as it goes, and automated code review checks each pull request. Repository owners still decide rollout order and merge each result. ## Further reading - [Configuration drift repair with coding agents](https://factory.com/articles/coding-agent-configuration-drift) - [Dependency updates with coding agents](https://factory.com/articles/coding-agent-dependency-updates) - [Test fixture maintenance with coding agents](https://factory.com/articles/coding-agent-test-fixture-maintenance) - [Node.js releases](https://nodejs.org/en/about/previous-releases)