What the agent does
The agent clones the program into its own cloud sandbox and reads what the stack manages before deciding what drift would look like. In a program like aws-ts-s3-folder in pulumi/examples, Pulumi.yaml declares a Node.js runtime with a template config for aws:region defaulting to us-west-2, and package.json pins @pulumi/pulumi at 3.228.0 and @pulumi/aws at 7.23.0 with mime, ts-node and TypeScript under an ESM tsconfig.json that compiles only index.ts. That one file creates an aws.s3.Bucket, a BucketWebsiteConfiguration with index.html as the index document, a BucketPublicAccessBlock with blockPublicAcls: false, one BucketObject per file under www with its MIME type from mime.getType, and a BucketPolicy that allows s3:GetObject to everyone, exporting bucketName and websiteUrl. Every one of those is a thing a person can change in the AWS console in a minute: re-enable the public access block, edit the policy, upload a new index.html over the top. The program's README covers pulumi up and pulumi destroy and nothing in between.
It adds .github/workflows/drift.yml that runs on a schedule and on workflow_dispatch. The job checks out the repository, sets up Node from the package.json engines or the version the agent finds in use, runs npm ci, and calls pulumi/actions with command: preview, refresh: true, expect-no-changes: true and diff: true against the stack named in a workflow input or variable. A refresh first reads every resource's real state from AWS and updates the stack's view of it; the preview then compares the program with that refreshed state, and expect-no-changes makes the step fail when they differ, which is exactly the definition of drift. The preview is read-only, so the workflow can never fix drift by accident. AWS credentials come from aws-actions/configure-aws-credentials assuming a role through OpenID Connect with id-token: write on the job, and the Pulumi backend from a PULUMI_ACCESS_TOKEN secret.
When the step fails, a final step runs only on failure and uses the gh CLI with the workflow's token to open an issue titled with the stack name and the date, containing the preview's diff from the step output, or to add a comment when an open issue with the drift label already exists, so a stack that drifts every night produces one thread rather than thirty issues. permissions on the job are contents: read, issues: write and id-token: write, nothing more. The schedule is one cron line a reviewer edits, and the stack name is a repository variable so the same workflow serves dev and prod through a matrix when the program has both.
It proves what it can without AWS credentials, which the sandbox does not have. It runs npm ci and npx tsc --noEmit to show the program still compiles, runs actionlint on the new workflow, and uses pulumi login --local with pulumi preview on a stack with no provider credentials to confirm the program parses and the stack name is wired through, stopping at the provider error it expects. The README gets a section on what drift means for this program, naming the three changes above, how to run the workflow by hand from the Actions tab, and that fixing drift is still a person running pulumi up or editing the program. The pull request says plainly that the first real refresh happens when the reviewer dispatches the workflow.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add drift detection to this Pulumi program. Read Pulumi.yaml, package.json, every program file and the README first, and list which resources a person could change outside Pulumi and what that would look like. Add a GitHub Actions workflow on a schedule and on manual dispatch that installs dependencies, authenticates to the cloud with OpenID Connect and to Pulumi with an access token secret, and runs a refreshed preview that fails when the refreshed state differs from the program, with the diff shown. On failure, open or update one issue per stack with the diff using the workflow token, with the least permissions that allow it. Make the stack name a variable so several stacks can share the workflow. Run the dependency install, the TypeScript check and actionlint in your sandbox, confirm the program parses with a local login, document what drift means for this program and how to dispatch the workflow in the README, and open a pull request that says the first real check runs when a reviewer dispatches it.",
"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 adding .github/workflows/drift.yml and a README section. The description lists the resources in the program and, for each, the out-of-band change that would show as drift, the secrets and variables the workflow expects by name, the permissions the job holds and why each is needed, and the tsc and actionlint output from the sandbox.
The run's record keeps the npm ci, the TypeScript check, the lint of the workflow and the local-login preview attempt, so a reviewer can see the program compiled, the workflow is well-formed and the stack name flows to the Pulumi step, and can see where the sandbox stopped for lack of cloud credentials rather than guess.
Before merging, a reviewer creates the OIDC role and the two repository settings the description names, dispatches the workflow once against dev to see a clean refreshed preview, then makes one deliberate change in the console and dispatches again to see the issue appear with the diff.
Run it on every new Pulumi program
A platform team with many programs hands this off from the terminal once per repository: one POST /o/{org}/sessions with this body and the repository in resources, and a request_id that is a UUID v5 of the repository name so a retried call returns the run it already started. The key's webhook_url reports each finished run with its pull request.
When the workflow later opens a drift issue, a handler on your server can receive GitHub's issues webhook for that label, check its signature, and start a run with the repository in resources and a prompt that reads the diff in the issue and proposes whether the program or the cloud should change, as a comment rather than a push. GitHub cannot add the Authorization header a Rush webhook trigger requires, so the handler sends the request itself, with a request_id that is a UUID v5 of the delivery id.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Drift detection is a workflow nobody notices until the day it matters, which is why it has to be right the first time: read-only, failing on exactly the condition it names, with the least permissions, and producing one thread per stack rather than a flood. The agent reads the real program to say what drift would look like for its resources, writes the workflow against that, and checks the parts it can check in its own sandbox, saying clearly which part only the reviewer's credentials can exercise.
The same body runs across every Pulumi program an organisation owns, each pull request carrying its own resource list and its own secrets and variables table. That is how a platform team gets a consistent answer to one question, has anyone changed this stack by hand, across programs written in different languages by different teams.
Frequently asked questions
Will the workflow ever change my infrastructure?
No. It runs preview with refresh: true, which reads the real state and compares it with the program; nothing is applied. Fixing drift stays a deliberate pulumi up by a person, or a change to the program, and the README section says so.
What counts as drift for this program?
Any difference between the refreshed state and index.ts. For the S3 website program that is a changed bucket policy, a re-enabled public access block, a changed website configuration, or a file under www that someone uploaded over the top, which shows as a different BucketObject source hash. The pull request lists each one.
Why open an issue instead of failing silently?
Because a red scheduled workflow is easy to miss and a red one every night is easy to ignore. The failure step opens one issue per stack with the diff and comments on it on later runs, so there is one thread with the history of the drift and a place to decide what to do.
Does it need long-lived cloud keys in GitHub?
No. The workflow assumes a role through OpenID Connect with id-token: write and aws-actions/configure-aws-credentials, so the only secret is the Pulumi access token for the backend. For a self-managed backend such as an S3 bucket, the pull request shows the one line that changes.
Can one workflow cover several stacks?
Yes. The stack name is a variable, and the pull request shows the matrix form that runs the same job for dev and prod in parallel, each failing and opening its own issue independently.