site-deploy-agent

An AWS Lambda function that listens for GitHub push webhooks and automatically syncs your static site to S3 and invalidates the CloudFront cache.

How It Works

GitHub push
    │
    ▼
GitHub sends POST /webhook (Lambda Function URL)
    │
    ▼
Lambda verifies HMAC-SHA256 signature
    │
    ▼
Downloads repo tarball via GitHub API
    │
    ▼
Syncs files to S3 (upload new/changed, delete stale)
    │
    ▼
CloudFront invalidation (/*)

No external dependencies — only Python stdlib and boto3 (pre-installed in the Lambda runtime).

---

Prerequisites

• An S3 bucket and CloudFront distribution already set up
• A GitHub personal access token with read access to the repo (Contents: read)

---

Setup

1. Create the Lambda function

1. Go to the AWS Lambda console → Create function
2. Choose Author from scratch
3. Set Function name to site-deploy-agent (or whatever you like)
4. Set Runtime to Python 3.12
5. Set Architecture to arm64
6. Click Create function

2. Paste the code

1. In the Code tab, open lambda_function.py in the inline editor
2. Replace its contents with the contents of agent.py from this repo
3. Click Deploy
4. In Runtime settings → Edit, set Handler to lambda_function.handler

3. Configure the function

In the Configuration tab:

General configuration → Edit:

• Timeout: 5 min 0 sec
• Memory: 512 MB

Environment variables → Edit — add the following:

Key	Value
GITHUB_WEBHOOK_SECRET	A secret you generate (e.g. a random string); use the same value as the webhook Secret in GitHub
GITHUB_REPO	Repository in owner/repo format
GITHUB_TOKEN	GitHub token with read access to the repo
DEPLOY_BRANCH	Branch that triggers a deploy (e.g. main)
SITE_SUBDIR	Subdirectory inside the repo to sync (blank = whole repo)
S3_BUCKET	S3 bucket name
S3_PREFIX	Key prefix inside the bucket (blank = bucket root)
CLOUDFRONT_DISTRIBUTION_ID	CloudFront distribution ID

4. Set IAM permissions

The function's execution role needs permission to read/write your S3 bucket and invalidate your CloudFront distribution.

In Configuration → Permissions, click the execution role link to open IAM, then attach an inline policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:DeleteObject", "s3:GetObject"],
      "Resource": "arn:aws:s3:::YOUR_BUCKET/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET"
    },
    {
      "Effect": "Allow",
      "Action": "cloudfront:CreateInvalidation",
      "Resource": "arn:aws:cloudfront::YOUR_ACCOUNT_ID:distribution/YOUR_DISTRIBUTION_ID"
    }
  ]
}

Replace YOUR_BUCKET, YOUR_ACCOUNT_ID, and YOUR_DISTRIBUTION_ID with your actual values.

5. Create a Function URL

1. In Configuration → Function URL → Create function URL
2. Set Auth type to NONE
3. Click Save

Copy the Function URL — it will look like https://<id>.lambda-url.<region>.on.aws/.

Your two endpoints are:

• POST https://<id>.lambda-url.<region>.on.aws/webhook — GitHub webhook receiver
• GET https://<id>.lambda-url.<region>.on.aws/health — health check

---

GitHub Webhook Setup

1. Go to your GitHub repo → Settings → Webhooks → Add webhook
2. Set Payload URL to https://<id>.lambda-url.<region>.on.aws/webhook
3. Set Content type to application/json
4. Set Secret to the same value you set for GITHUB_WEBHOOK_SECRET (the secret you generated)
5. Under Which events, choose Just the push event
6. Click Add webhook

Push to your configured branch — CloudWatch Logs will show the deploy progress.