diff --git a/.github/workflows/test-installer.yml b/.github/workflows/test-installer.yml
new file mode 100644
index 000000000..b645cc5f3
--- /dev/null
+++ b/.github/workflows/test-installer.yml
@@ -0,0 +1,116 @@
+name: Test installer.sh
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'CLI version to install for raw tests (leave empty for latest release)'
+        required: false
+        type: string
+  push:
+    branches:
+      - main
+    paths:
+      - installer.sh
+      - .github/workflows/test-installer.yml
+  pull_request:
+    paths:
+      - installer.sh
+      - .github/workflows/test-installer.yml
+
+permissions:
+  contents: read
+
+jobs:
+  # Default install flow: the installer auto-detects the package manager.
+  # CI is overridden to empty so that is_ci() returns false (otherwise
+  # the installer would always select the "raw" method on Linux).
+  linux:
+    runs-on: ubuntu-latest
+    container: ${{ matrix.image }}
+    defaults:
+      run:
+        shell: sh
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: debian:bookworm
+            prereqs: apt-get update && apt-get install -y curl ca-certificates
+          - image: ubuntu:24.04
+            prereqs: apt-get update && apt-get install -y curl ca-certificates
+          - image: fedora:41
+            prereqs: yum install -y curl
+          - image: alpine:3.21
+            prereqs: apk add --no-cache curl ca-certificates
+
+    steps:
+      - name: Install prerequisites
+        run: ${{ matrix.prereqs }}
+
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Run installer
+        env:
+          CI: ""
+        run: sh installer.sh
+
+      - name: Verify installation
+        run: upsun --version
+
+  # Raw install on Linux: setting VERSION triggers the raw method.
+  # Without a VERSION input the installer queries the GitHub API for the
+  # latest release.
+  linux-raw:
+    runs-on: ubuntu-latest
+    container: debian:bookworm
+    defaults:
+      run:
+        shell: sh
+    steps:
+      - name: Install prerequisites
+        run: apt-get update && apt-get install -y curl ca-certificates gzip
+
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Run installer
+        env:
+          VERSION: ${{ inputs.version }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: sh installer.sh
+
+      - name: Verify installation
+        run: upsun --version
+
+  # Default install flow on macOS (auto-detects homebrew).
+  macos:
+    runs-on: macos-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Run installer
+        run: sh installer.sh
+
+      - name: Verify installation
+        run: upsun --version
+
+  # Raw install on macOS (INSTALL_METHOD is required because VERSION
+  # does not affect macOS method selection).
+  macos-raw:
+    runs-on: macos-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Run installer
+        env:
+          INSTALL_METHOD: raw
+          VERSION: ${{ inputs.version }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: sh installer.sh
+
+      - name: Verify installation
+        run: upsun --version
diff --git a/scripts/test/installer.sh b/scripts/test/installer.sh
new file mode 100755
index 000000000..a76384bad
--- /dev/null
+++ b/scripts/test/installer.sh
@@ -0,0 +1,75 @@
+#!/bin/sh
+# Test installer.sh across Linux distros using Docker.
+# Requires Docker to be installed and running.
+# macOS methods (homebrew, raw) are only tested in CI (GitHub Actions).
+
+set -eu
+
+cd "$(dirname "$0")/../.."
+
+: "${VERSION:=}"
+
+pass=0
+fail=0
+errors=""
+
+# Run a test in a Docker container.
+# Arguments: label, image, prereqs, [extra docker args...]
+run_test() {
+    label="$1"
+    image="$2"
+    prereqs="$3"
+    shift 3
+
+    echo ""
+    echo "=== ${label} ==="
+
+    if docker run --rm \
+        -v "$(pwd)/installer.sh:/installer.sh:ro" \
+        "$@" \
+        "$image" \
+        sh -c "${prereqs}sh /installer.sh && upsun --version"; then
+        echo "--- PASS: ${label} ---"
+        pass=$((pass + 1))
+    else
+        echo "--- FAIL: ${label} ---"
+        fail=$((fail + 1))
+        errors="${errors}  ${label}\n"
+    fi
+}
+
+echo "installer.sh test suite"
+echo "======================="
+
+# Default flow tests: let the installer auto-detect the install method.
+
+run_test "debian:bookworm (default)" "debian:bookworm" \
+    "apt-get update -qq && apt-get install -y -qq curl ca-certificates && "
+
+run_test "ubuntu:24.04 (default)" "ubuntu:24.04" \
+    "apt-get update -qq && apt-get install -y -qq curl ca-certificates && "
+
+run_test "fedora:41 (default)" "fedora:41" \
+    "yum install -y -q curl && "
+
+run_test "alpine:3.21 (default)" "alpine:3.21" \
+    "apk add -q --no-cache curl ca-certificates && "
+
+# Raw install test: setting VERSION triggers the raw method on Linux.
+if [ -n "$VERSION" ]; then
+    run_test "debian:bookworm (raw, VERSION=$VERSION)" "debian:bookworm" \
+        "apt-get update -qq && apt-get install -y -qq curl ca-certificates gzip && " \
+        -e "VERSION=${VERSION}"
+else
+    echo ""
+    echo "Skipping raw install test (set VERSION to enable)"
+fi
+
+echo ""
+echo "======================="
+echo "Results: ${pass} passed, ${fail} failed"
+
+if [ "$fail" -gt 0 ]; then
+    printf "\nFailed:\n%b" "$errors"
+    exit 1
+fi