AWS Lightsail Provider

Deploy preview environments to AWS Lightsail instances via SSH.

How it works

• Build: SSHs into a fresh Lightsail instance, clones the repo, and runs docker build. Docker and git are installed automatically via launch script on first boot.
• Deploy: runs the built Docker image on the same instance. Each PR gets its own Lightsail instance.
• Delete: terminates the Lightsail instance.
• List: lists all Lightsail instances tagged previewops: true for the repo.

Prerequisites

1. An AWS account.
2. An IAM user or role with Lightsail permissions.
3. An SSH key pair for instance access.

Step 1 — Create IAM credentials

Create an IAM user (or use an existing role) with the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lightsail:CreateInstances",
        "lightsail:DeleteInstance",
        "lightsail:GetInstance",
        "lightsail:GetInstances",
        "lightsail:TagResource"
      ],
      "Resource": "*"
    }
  ]
}

1. Go to IAM → Users → Create user → Attach policies directly (paste the JSON above as an inline policy).
2. Create an Access Key for the user.
3. Store the credentials:

Step 2 — Create an SSH key pair

ssh-keygen -t ed25519 -C "previewops-lightsail" -f ~/.ssh/previewops-lightsail

Store the private key content as AWS_SSH_PRIVATE_KEY in Previewops secrets:

cat ~/.ssh/previewops-lightsail

Note: The SSH key must match a key pair registered in your Lightsail account. The provider uses your account's default key pair by default — download its private key from the Lightsail console under Account → SSH keys. If you generated a new key pair, import the public key there first under Custom keys → Upload new.

Step 3 — Configure the repo

All providerConfig fields are optional:

provider: aws-lightsail
providerConfig:
  region: us-east-1          # optional (default: us-east-1)
  bundleId: nano_2_0         # optional (default: nano_2_0) — instance size
                             # see: aws lightsail get-bundles
  blueprintId: ubuntu_22_04  # optional (default: ubuntu_22_04) — OS image
                             # see: aws lightsail get-blueprints

Step 4 — Verify

Comment /validate-previewops on any open PR. The bot calls GetInstances against the Lightsail API (which requires valid credentials) and reports the result.

Notes

• Instances are provisioned on-demand for each PR and terminated on delete/close.
• First deploy takes ~3 minutes (instance boot + Docker/git installation).
• Subsequent deploys to the same PR reuse the existing instance (~30s).
• The preview URL is http://{instance-public-ip}.
• nano_2_0 ($3.50/month, prorated) is the minimum; use micro_2_0 or larger for heavier workloads.

Troubleshooting