Recommended AWS setup — PullPreview docs

PullPreview drives AWS Lightsail entirely through the Lightsail API, so the credentials it runs with can be locked down tightly. This page covers the recommended setup: short-lived credentials via GitHub OIDC and a least-privilege IAM policy. The Getting started guide uses long-lived access keys for simplicity, but for anything beyond a quick trial, prefer the approach below.

Use GitHub OIDC + AssumeRole (recommended)

Instead of storing long-lived AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY secrets, let GitHub Actions request short-lived credentials at runtime via OpenID Connect. GitHub exchanges an OIDC token for temporary credentials by assuming an IAM role you control.

In your workflow:

Grant the id-token: write permission so the job can request an OIDC token.
Use aws-actions/configure-aws-credentials with role-to-assume to assume your role.
Run PullPreview after credentials are configured — it picks up the temporary credentials from the environment automatically.

permissions:
  id-token: write
  contents: read
  pull-requests: write

steps:
  - uses: actions/checkout@v6
  - name: Configure AWS credentials (OIDC)
    uses: aws-actions/configure-aws-credentials@v5
    with:
      role-to-assume: arn:aws:iam::123456789012:role/pullpreview
      aws-region: us-east-1
  - uses: pullpreview/action@v6

Lightsail defaults to the us-east-1 region. Set aws-region to wherever you want your preview instances created.

For the one-time setup of the OIDC identity provider and role, see the official docs:

Restrict the IAM policy

PullPreview only calls the Lightsail API, so the role it assumes needs nothing more than Lightsail access. Attach a least-privilege policy that grants only lightsail:*:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["lightsail:*"], "Resource": "*" }
  ]
}

Also restrict the role’s trust policy to your repository (and optionally a specific branch or environment) using OIDC token conditions. This prevents other repositories from assuming the role even if they could reach your AWS account.

Use an isolated AWS account (optional)

For stronger security and billing separation, create a dedicated AWS account for preview environments and place the OIDC role there. Preview workloads then run fully isolated from your production account, and their cost shows up on a separate bill. See AWS: Creating a member account in your organization ↗.

Fallback: dedicated IAM user

If OIDC is not an option in your setup, create a dedicated IAM user scoped to PullPreview only, with a dedicated access key pair, and apply the same least-privilege lightsail:* policy. Store the key pair as the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets as shown in Getting started. Both long-lived keys and OIDC AssumeRole are supported — OIDC is just the more secure default.

For details on how credentials are passed to the action and how other providers are configured, see Providers and Configuration reference.