# Pull request workflow

Use this workflow for every infrastructure or application change.

## Prerequisites

Install Git, Terraform, TFLint, and the GitHub CLI. Authenticate the GitHub CLI with StormTrust access. Application changes also require Node.js and pnpm.

1. Clone the repository and create a branch.  
```sh  
gh repo clone StormTrust/infrastructure  
cd infrastructure  
git checkout -b <SHORT_NAME>  
```
2. Edit the owning root or application. Format and verify the repository.  
```sh  
make fmt  
make verify  
```  
For an application change, also run `make app-verify APP=<APP>` for each affected app. Follow [Validate a change](/stormtrust/engineering/operations/validate/) for selection and package checks.
3. Commit the change, push the branch, and open a pull request.  
```sh  
git add <CHANGED_FILES>  
git commit -m "Describe the change"  
git push -u origin HEAD  
gh pr create --fill  
```
4. Review the single **Terraform Plan** comment. Confirm every affected root, application verification, and application deployment. Runtime consumers may need verification without deployment. The comment updates after each run.
5. After the plan succeeds, add the `terraform-apply` label when infrastructure or deployments are selected. Verification-only changes need no label. The workflow creates a fresh plan and updates ` Apply authorized`.
6. Merge after `Verify`, ` Plan`, and ` Apply authorized` succeed. The ` main`workflow plans again, applies selected Terraform roots, verifies R2 state, and packages each deployable application. Dependency stages deploy those verified packages without rebuilding code. The gateway deploys last.

## Application release packages

`org/catalog.json` records application ownership and exceptional dependencies. Shared tooling infers ordinary dependencies from local package references and Wrangler service bindings. Plain Workers use the root toolchain and require no app-specific release scripts. Run ` make app-create APP=<name>` to create a Worker with its Terraform declaration and catalog registration. Changes to bundled code rebuild consumers. Changes to runtime services verify consumers without automatically redeploying them.

Release packages contain compiled Worker modules, assets, owned migrations, configuration, a commit SHA, and file checksums. Production identifiers are resolved on a separate deployment copy. The workflow records deployment receipts and the artifact checksum.

Follow [Deploy a change](/stormtrust/engineering/operations/deploy/) to inspect release evidence and [Recover a release](/stormtrust/engineering/operations/recover/) to retry or correct a failed deployment. Confirm the intended revision before retrying, especially if a newer release has already deployed.

## Retry a plan

Add the `terraform-plan` label to retry a transient plan failure. The workflow removes the label after it starts and updates the existing plan comment.

Caution

Do not run a normal Terraform apply from a workstation. Use the documented R2 recovery procedure only for a break-glass state recovery.