Terraform-first deployment
Use Brix to prepare and verify application inputs, and project-owned Terraform to manage resources, configuration, and traffic. There is no Brix deployment command, target registry, or state manager. Explicit snapshot and artifact publishing can precede Terraform; Brix does not reimplement Terraform. Release publication is separate from application deployment.
Start with existing infrastructure
#Inspect existing Terraform state, providers, backend, IAM, environment schemas, build setup, and
deployment approvals before changing anything. Preserve resources and ownership; use reviewed
imports, moved blocks, or state moves and a no-destroy plan when adopting old addresses. Bootstrap
the backend separately. Its account may differ from runtime providers: each needs independent guards.
The editable recipe ships in the installed package at
node_modules/brix/templates/deployment/aws-lambda and demonstrates custom Lambda
workers without browser assets, existing runtime IAM roles, and a bootstrapped backend. Copy and
adapt it to your project; read its README for current invocation details. It is not a universal
HTTP/asset deployment module. Use the same project-owned script locally and in CI, with different
authentication and approval adapters. Reviewed target tfvars JSON supplies target identity and bindings.
Uploads and Terraform apply change shared state and require explicit authorization. Script checks are guardrails, not access control; enforce authorization with IAM and protected environments.
Verify prepared artifacts offline
#import { verifyDeploymentArtifact } from "brix/artifacts";
const verified = await verifyDeploymentArtifact("apps/worker/dist/deployment", {
target: "aws-lambda",
source: { revision: approvedRevision, project: "apps/worker", clean: true },
});
// Persist verified.manifestSha256 with the deployment record.
This Node-only API checks manifest schema, canonical package hashes, asset inventory, and Lambda
safe ZIP limits. Fastly's fastly-compute tarball is verified without extraction. It needs neither
credentials nor a checkout. source.clean: true requires a build from a clean checkout; false
or omission accepts either. Expected source.project is the app workspace path;
build.application is an entry filename, not identity. manifestSha256 hashes the exact
deployment.json bytes, not the nested build manifest. Integrity is not provenance attestation,
and this is not a validator for arbitrary repackaged ZIPs.
Prepare all environments before any write
#import { prepareEnvUpload, uploadAwsEnvSnapshot } from "brix/env/upload";
// applications and target come from reviewed project configuration.
const prepared = [];
for (const application of applications) {
prepared.push(
await prepareEnvUpload({
root: application.root,
stage: target.stage,
bindings: application.bindings,
}),
);
}
for (const [index, handle] of prepared.entries()) {
// Project adapter persists the token BEFORE mutation; never print values.
const requestToken = await persistRequestToken(index);
const receipt = await uploadAwsEnvSnapshot(handle, {
accountId: target.accountId,
region: target.region,
requestToken,
});
await persistReceipt(index, receipt);
}
These are Node-only APIs. Preparation resolves schema/base/stage once, excludes local files,
rejects injected snapshot context, and returns an opaque process-local handle, not serialized
values. It does not mutate process.env. Ambient application keys fail unless explicitly named
in overrides; internal provider authentication is allowed. Bindings must be declared and
non-sensitive. Prepare every application before any upload so a later schema failure cannot leave
an earlier application published. The API does not export CI variables.
Upload validates its inputs before contacting AWS: accountId must be 12 digits, region an
explicit AWS region such as eu-west-1, and requestToken 32–64 letters, digits, or hyphens (a
crypto.randomUUID() value qualifies). It resolves credentials once for both STS and the write,
checks the target account before writing, and uses the explicit region without ambient service endpoint overrides. It checks exact
response identity and returns { format: "brix-env-upload-v1", accountId, region, stage, name, arn, versionId }. There is no mandatory readback, automatic retention, or promotion. See
environment secrets for the CLI adapter and override consent.
Persist tokens and receipts durably. The same token and bytes retry idempotently; an error may represent a successful write. Do not blindly generate new tokens or rerun preparation with changed provider values. Inspect remote metadata and reconcile uncertain outcomes without logging secrets.
Approve the computed plan
#Publish verified packages, then bind exact snapshot ARN/version receipts in Terraform. Protect saved plans because they can contain secrets. Record artifact and snapshot identities with the plan:
terraform plan -out=deployment.tfplan -var-file=target.tfvars.json
sha256sum deployment.tfplan
# Obtain approval for this digest; revalidate artifact bytes before applying.
terraform apply deployment.tfplan
A protected GitHub environment gate before a job is not approval of the plan computed later. Apply only the digest-approved saved plan, not a regenerated one. For HTTP builds, publish and verify assets before activation and preserve delivery metadata. Terraform owns resource/traffic decisions; health checks are project-defined, and scripts cannot infer health from successful apply.
Define recovery policy explicitly
#Coordinate concurrency across local and CI, including uploads and approvals, not merely Terraform's backend lock. Define partial-apply recovery by inspecting actual state and provider versions before retrying. Never label a snapshot live solely because apply succeeded. Retain active, rollback, and pending snapshots, packages, and assets; own labels, cleanup, and provider quota limits. AWS may remove unlabeled old versions. Brix does not automatically retain or roll back them.
Build once and promote the same bytes when possible. Stage-specific CDN origins or build-time values make artifacts specific to those inputs. Validate the candidate with representative events or public HTTP and asset checks before changing traffic; local tests do not establish remote permissions.