What the agent does
The agent reads the program and what pins it. In a Pulumi project like aws-ts-s3-folder in pulumi/examples, package.json pins @pulumi/aws at 7.23.0 and @pulumi/pulumi at 3.228.0 exactly, with carets on mime ^4.0.0, ts-node ^10.9.2 and typescript ^5.9.3, and @types/node pinned at 22.13.14; there is no lockfile in the directory. Pulumi.yaml declares the nodejs runtime and an aws:region config with a default of us-west-2. index.ts creates an aws.s3.Bucket, a BucketWebsiteConfiguration, a BucketPublicAccessBlock with blockPublicAcls: false, one BucketObject per file in www/ with mime.getType for the content type, and a BucketPolicy that dependsOn the access block, then exports bucketName and websiteUrl. tsconfig.json compiles only index.ts, strictly, as nodenext modules.
Upgrading a Pulumi program is mostly about the provider. The agent runs npm install and npm outdated to see where each package stands, then reads the release notes of @pulumi/aws between the pinned version and the newest, because provider releases change resource schemas: an input renamed, a default that now plans a replacement, a resource deprecated in favour of a successor. It keeps the file's style, exact pins for the two Pulumi packages and carets elsewhere, bumps minors and patches, and treats a major version of @pulumi/aws as its own decision: taken only if the notes show nothing that touches the five resource types this program uses, otherwise left out with the reason and the link.
Then it checks. npx tsc --noEmit compiles index.ts against the new typings, which catches a renamed input or a changed output type before anything reaches a cloud. pulumi preview is the real test, and it needs two things the sandbox does not have by default: a backend and AWS credentials. The agent logs in to a local backend with pulumi login --local and a passphrase, creates a throwaway stack, and runs the preview when the Project supplies AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as Project secrets, which reach every session in that Project as environment variables. Without them the agent stops at type checking and says so in the pull request rather than pretending.
What the preview must show is the point of the exercise. A pure dependency bump of a deployed stack should plan no changes; a provider upgrade may plan updates to resource metadata, which is fine, or a replace of the bucket, which is not, because it would recreate the bucket and its objects. The agent pastes the preview's resource table and calls out any replace or delete line. The pull request lists each bump as package: old -> new with the resolved versions, and records that no lockfile was added because the directory keeps none.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade the npm dependencies of this Pulumi TypeScript program and open a pull request. Read package.json, Pulumi.yaml, index.ts and tsconfig.json first. Run npm install and npm outdated, then read the release notes of @pulumi/aws and @pulumi/pulumi between the pinned and the newest versions. Keep the file's style, exact versions for the Pulumi packages and caret ranges for the others. Bump minor and patch versions; take a major version of @pulumi/aws only if its notes show no change to the resource types index.ts uses, otherwise leave it out and say why with a link. Run npx tsc --noEmit. If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are present in the environment, run pulumi login --local, create a stack with a passphrase, set aws:region, run pulumi preview and paste its resource table, calling out any replace or delete line; if they are absent, say the preview was skipped and why. Do not add a lockfile if the directory has none, and do not run pulumi up. List every bump in the pull request as package, old version, new version.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes package.json only, one line per package moved, with a description listing each bump as package, old version and new version, links to the release notes that were read, and the tsc --noEmit output. When credentials were available, the pulumi preview resource table is pasted with any replace or delete line called out; when they were not, the description says the preview was skipped and why.
In the examples repository, Renovate is configured in renovate.json5 with a weekday schedule and separate pull requests per major and minor, and a nightly test-examples.yml sweep runs Go acceptance tests against every example with credentials from Pulumi ESC; a standalone program has whatever workflow its team keeps, and the pull request runs it.
A reviewer checks that a major provider bump was either taken with evidence or deferred with a reason, that the preview shows no replacement of the bucket, and that the pinning style is unchanged. Then they merge and let the next deploy carry the new provider.
Run it on every Monday morning
A scheduled job on your server sends POST /o/{org}/p/{project}/sessions each week with this request and the repository in resources, in the Project that holds the AWS credentials as secrets so the preview runs. Send a request_id that is a UUID v5 of the repository and the week; a retry with the same id and body returns the run already started instead of opening a second pull request.
Give the API key a webhook_url and Rush POSTs run.completed when the turn ends, with the session_url to read the pull request link from, so the weekly diff and its preview table land where the infrastructure team reviews changes.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A dependency bump in an infrastructure program is not safe because it compiles; it is safe because the preview planned nothing destructive. Running that preview by hand means a developer with cloud credentials, a backend and twenty spare minutes each week. In a Rush sandbox the agent installs, type-checks, logs in to a local backend and previews with the Project's secrets, and every command and the preview's table are kept in the run's record.
The judgment is written down rather than remembered. Which provider major was skipped and why, which release note mattered, which line in the preview would have recreated the bucket: all of it is in the pull request, and the same request runs on every Pulumi program the team owns, each in its own sandbox.
Frequently asked questions
Does it need AWS credentials?
Only for the preview. Type checking runs without them. Save AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as Project secrets and start the session in that Project; they reach the sandbox as environment variables and pulumi preview can configure the provider. Without them the pull request says the preview was skipped.
Why keep exact pins for the Pulumi packages?
Because the program already does, and the provider version decides what the preview plans. A caret on @pulumi/aws would let two installs of the same commit plan different changes. The agent moves the pin and leaves the carets on mime, ts-node and typescript as they were.
What happens on a major @pulumi/aws release?
The agent reads the release notes for the resource types index.ts uses: Bucket, BucketWebsiteConfiguration, BucketPublicAccessBlock, BucketObject and BucketPolicy. If nothing there changes, it takes the bump and shows the preview; otherwise it leaves the major out, links the note, and the team decides in a separate pull request.
Does it run pulumi up?
Never. The prompt forbids it and the agent works on a throwaway local stack created only to preview. Applying the change is a deploy, done by your pipeline from the merged branch.
Does it upgrade the Pulumi CLI too?
No. The CLI is a tool on the machine that deploys, not a dependency in package.json. The agent uses whatever CLI is in the sandbox for the preview and notes its version in the description so a mismatch with your pipeline is visible.
More Pulumi jobs
The same job on other stacks
- Upgrade npm Dependencies in a React Router App (React Router)
- Upgrade npm Dependencies in a SolidJS App (SolidJS)
- Upgrade npm Dependencies in a Temporal TypeScript Project (Temporal)