Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (49 loc) · 2.82 KB

CONTRIBUTING.md

File metadata and controls

69 lines (49 loc) · 2.82 KB
Raw

Contributing

Thanks for your interest in improving this module. This is a Terraform module that runs GitHub Actions self-hosted runners on AWS Lambda MicroVMs; the design is documented in docs/ARCHITECTURE.md.

Prerequisites

To work on the module you need the same tools the module needs at terraform apply time (the dispatcher Lambda zip is built locally via a local-exec step):

  • Terraform ≥ 1.9 (>= 1.9.0; CI pins the exact version)
  • python3 + pip, zip, bash — to build the dispatcher package
  • terraform-docs — to regenerate the inputs/outputs table in the README

You do not need AWS credentials to format, validate, or regenerate docs.

Local checks

Run these before opening a PR — CI runs the same ones:

terraform fmt -recursive          # format all .tf files
terraform init -backend=false     # download providers (no state/credentials)
terraform validate                # validate the root module

# validate the example too
( cd examples/github-app && terraform init -backend=false && terraform validate )

# regenerate the README inputs/outputs/resources table (reads .terraform-docs.yml)
terraform-docs .

# sanity-check the Python
python -m py_compile dispatcher/handler.py microvm/entrypoint.py

If you change any variable/output/resource, re-run terraform-docs . — the <!-- BEGIN_TF_DOCS --> block in the README is generated, and CI fails if it drifts.

Changing the runner image

The MicroVM image is built by Lambda from microvm/Dockerfile + microvm/entrypoint.py + microvm/wait-for-docker.sh (zipped to S3 — see docs/ARCHITECTURE.md §4). Editing any of those files changes the artifact hash, so the next terraform apply builds a new image version and the dispatcher picks it up automatically. The first build takes a few minutes (it boots the app and snapshots it).

Changing the dispatcher

dispatcher/handler.py (+ dispatcher/requirements.txt) is packaged by scripts/build-dispatcher.sh, which Terraform invokes automatically. The Lambda redeploys whenever the handler, requirements, or build script change. Keep the handler dependency-light; the only bundled third-party deps are PyJWT + cryptography (arm64 wheels).

Pull requests

  • Keep changes focused; update the docs (README.md, docs/USAGE.md, docs/ARCHITECTURE.md) when behavior or inputs change.
  • Add a line under ## [Unreleased] in CHANGELOG.md.
  • Never commit secrets, *.tfstate, *.tfvars (except *.tfvars.example), or the GitHub App private key. .gitignore already excludes them.
  • Write clear commit messages that explain why, not just what.

License

By contributing you agree that your contributions are licensed under the MIT License.