# Add Drift Detection to a Pulumi Program

Yes. An agent adds a scheduled workflow that refreshes your Pulumi stack, fails on any change the program did not make, and opens an issue with the diff.

[Run this on Rush](https://cloud.getrush.ai/run/add-drift-detection/pulumi/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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.

## More Pulumi jobs

- [Set Up GitHub Actions CI for a Pulumi Project](https://getrush.ai/run/add-github-actions-ci/pulumi/)
- [Add a Policy Pack to a Pulumi Program](https://getrush.ai/run/add-policy-pack/pulumi/)
- [Post Pulumi Previews on Pull Requests](https://getrush.ai/run/add-preview-comments-to-pr/pulumi/)

## The same job on other stacks

- [Add Terraform Drift Detection to an EKS Configuration](https://getrush.ai/run/add-drift-detection/terraform/)
- [Add Drift Detection to Flux Helm Releases](https://getrush.ai/run/add-drift-detection/flux/)

## More jobs like this: Hand off a long task

- [Add a --dry-run Flag to a Cobra CLI](https://getrush.ai/run/add-dry-run-flag/cobra/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
