repro-lambda

Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf.

Produces byte-identical zip files across local dev (macOS) and CI (Linux), uploads to S3 by content-hash key, and lets Terraform read s3_existing_package instead of building during terraform plan/apply.

Install

pip install repro-lambda

Quick start

repro-lambda lock                     # regenerate per-arch requirement + source locks
repro-lambda build --bucket <bucket>  # build all lambdas in lambdas.toml, upload to S3
repro-lambda build --verify --dry-run # two-pass byte-reproducibility check (no upload)
repro-lambda promote \
  --dev-bucket <dev> --prod-bucket <prod>  # copy dev -> prod by content sha (no rebuild)

--bucket (or REPRO_LAMBDA_BUCKET) is required for a real build; add --dry-run to build without uploading. There is no init command yet (the subcommand is currently a stub).

Documentation

What each document covers, by section:

Setup - one-time AWS provisioning (SETUP.md)

Provision the supporting infrastructure once per AWS account and environment.

• Architecture - artifact buckets, key-level immutability, the content-hash model
• Terraform - per-account bootstrap - the buckets, the GitHub OIDC builder role, and outputs
• GitHub OIDC provider - declaring the shared per-account OIDC provider
• Next steps - where to go after provisioning

Usage - day-to-day (USAGE.md)

Using repro-lambda once the infrastructure exists.

• Source-repo CI workflow - wiring the reusable build workflow into CI/CD
• Per-Lambda manifest - the lambdas.toml fields
  • Per-lambda builder overrides - per-lambda base image and file filters
• Declarative sources - pinned external artifacts via [[lambda.source]]
• Terraform consumer (s3_existing_package) - wiring terraform-aws-modules/lambda/aws to the built artifact
• Smoke test - first-build verification and the clean migration plan diff
• Troubleshooting - upload 403s, PreconditionFailed, noisy plans
• Node.js (npm) Lambdas - npm packaging support
  • Manifest fields for npm specs
  • Lockfile regeneration
• Lambda@Edge example - us-east-1 artifacts for CloudFront
• Caveats - npm workspaces, native deps, symlinks

Example - runnable (examples/complete/)

A self-contained consumer setup: manifest, catalog, and Terraform using terraform-aws-modules/lambda/aws.

• What this example shows - files and layout
• The build-outside-Terraform flow - build, inspect the catalog, apply
• Expected plan diff - the s3_key-only diff to expect

License

MIT - see LICENSE.

Author

Anton Babenko - @antonbabenko on Twitter, antonbabenko on LinkedIn.