@@ -236,34 +236,42 @@ jobs:
           - elixir: "1.18.4"
             otp: "27.3.4.3"
 
+          # keep version in sync with integration_test/.env
           - elixir: "1.20.4"
             otp: "29.0.5"
 
     env:
       ELIXIR_ASSERT_TIMEOUT: 10000
       PHX_CI: true
-      # Set to half of the runner vCPU cores to compile deps/NIFs
-      # concurrently across OS processes without CPU oversubscription.
-      # See https://docs.github.com/en/actions/reference/runners/github-hosted-runners#standard-github-hosted-runners-for-public-repositories
-      # and https://elixir-lang.org/blog/2025/10/16/elixir-v1-19-0-released/
-      MIX_OS_DEPS_COMPILE_PARTITION_COUNT: 2
-      MAKEFLAGS: "-j2"
 
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
+      - name: Configure runner concurrency
+        run: |
+          CORES=$(nproc)
+          HALF_CORES=$(( CORES > 2 ? CORES / 2 : 2 ))
+          echo "CORES=$CORES" >> "$GITHUB_ENV"
+          echo "HALF_CORES=$HALF_CORES" >> "$GITHUB_ENV"
+          # Set to half of the runner vCPU cores to compile deps/NIFs
+          # concurrently across OS processes without CPU oversubscription.
+          # See https://elixir-lang.org/blog/2025/10/16/elixir-v1-19-0-released/
+          echo "MIX_OS_DEPS_COMPILE_PARTITION_COUNT=$HALF_CORES" >> "$GITHUB_ENV"
+          echo "MAKEFLAGS=-j$HALF_CORES" >> "$GITHUB_ENV"
+
       - name: Mount installer/tmp on tmpfs
         run: |
           mkdir -p installer/tmp
           sudo mount -t tmpfs -o size=4G,uid=$(id -u),gid=$(id -g) tmpfs installer/tmp
 
       - name: Start database container (${{ matrix.service }})
         if: matrix.service != 'none'
+        working-directory: integration_test
         run: |
-          docker compose -f integration_test/docker-compose.yml up -d --wait ${{ matrix.service }}
+          docker compose -f docker-compose.yml -f docker-compose.ports.yml up -d --wait ${{ matrix.service }}
 
       - name: Set up Elixir
         uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1
@@ -297,14 +305,15 @@ jobs:
           if [ "${{ matrix.service }}" = "none" ]; then
             FLAGS="--include database:sqlite3"
           else
-            FLAGS="--include database:${{ matrix.service }} --only database:${{ matrix.service }}"
+            FLAGS="--only database:${{ matrix.service }}"
           fi
 
           mix test $FLAGS \
+            --max-cases "$CORES" \
             --formatter ExUnit.CLIFormatter \
             --formatter Phoenix.Integration.SummaryFormatter
         env:
-          PHX_TEST_SERVICE: ${{ matrix.service }}
+          PHX_TEST_JOB: ${{ matrix.service }}
           PHX_ELIXIR_VERSION: ${{ matrix.versions.elixir }}
           PHX_OTP_VERSION: ${{ matrix.versions.otp }}
           PHX_INTEGRATION_SUMMARY_JSON: ${{ runner.temp }}/summary-${{ matrix.service }}-${{ matrix.versions.otp }}-${{ matrix.versions.elixir }}.json
@@ -326,6 +335,7 @@ jobs:
     timeout-minutes: 2
     needs: integration-test-elixir
     if: always()
+    continue-on-error: true
 
     steps:
       - name: Checkout
@@ -344,9 +354,7 @@ jobs:
         with:
           pattern: summary-*
           merge-multiple: true
-          path: tmp/summaries
+          path: ${{ runner.temp }}/summaries
 
       - name: Aggregate test summaries
-        run: elixir integration_test/aggregate_summary.exs tmp/summaries
-        env:
-          MATRIX_RESULT: ${{ needs.integration-test-elixir.result }}
+        run: elixir integration_test/aggregate_summary.exs "${{ runner.temp }}/summaries" >> "$GITHUB_STEP_SUMMARY"
@@ -16,6 +16,7 @@
 
 /integration_test/_build/
 /integration_test/deps/
+/integration_test/tmp/
 
 erl_crash.dump
 phoenix-*.ez
 
@@ -0,0 +1,7 @@
+# Default image tag for integration test runner (must be an Ubuntu-based hexpm/elixir image)
+# Keep Elixir and Erlang/OTP versions in sync with the latest matrix entry in .github/workflows/ci.yml
+#
+# Find Ubuntu image tags on Bob:
+# - Web UI: https://bob.hex.pm/docker?repo=hexpm/elixir&os=ubuntu&os_version=noble-&sort=elixir_version,erlang_version,os_version
+# - API: https://bob.hex.pm/api/docker?repo=hexpm/elixir&os=ubuntu&os_version=noble-&sort=elixir_version,erlang_version,os_version
+ELIXIR_IMAGE_TAG=1.20.4-erlang-29.0.5-ubuntu-noble-20260810
@@ -0,0 +1,25 @@
+ARG ELIXIR_IMAGE_TAG
+
+FROM hexpm/elixir:${ELIXIR_IMAGE_TAG}
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential git socat \
+    && rm -rf /var/lib/apt/lists/* \
+    && if id -u ubuntu >/dev/null 2>&1; then \
+        usermod -l runner -d /home/runner -m ubuntu && groupmod -n runner ubuntu; \
+    else \
+        useradd -m -u 1000 -s /bin/bash runner; \
+    fi \
+    && mkdir -p /home/runner/.mix /home/runner/.hex /phoenix/integration_test/_build /phoenix/integration_test/deps /phoenix/installer/tmp \
+    && chown -R runner:runner /home/runner /phoenix
+
+USER runner
+WORKDIR /phoenix/integration_test
+
+RUN mix local.hex --force \
+    && mix local.rebar --force
+
+COPY --chmod=755 entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["--include", "database"]
@@ -1,33 +1,66 @@
 ## Phoenix Integration Tests
 
-This project contains integration tests for phoenix's generated projects.
+This project contains integration tests for Phoenix's generated projects.
 
-## Running tests
+## Running Tests
 
-To install dependencies, run:
+### Option A: Using Docker & Docker Compose (Recommended)
+
+Run the integration test suite in an isolated container without needing local database or Elixir setup:
+
+    $ ./docker.sh
+
+Pass specific test files or tag filters to target individual tests:
+
+    $ ./docker.sh test/code_generation/app_with_defaults_test.exs --include database
+    $ ./docker.sh --include database:postgresql
+
+To test against different Elixir or Erlang/OTP versions:
+
+    $ ELIXIR_IMAGE_TAG=1.18.5-erlang-27.3.4.17-ubuntu-noble-20260810 ./docker.sh
+
+Find valid image tags (Ubuntu-based, `hexpm/elixir` repo) on [bob.hex.pm](https://bob.hex.pm/docker?repo=hexpm/elixir&os=ubuntu&os_version=noble-&sort=elixir_version,erlang_version,os_version).
+
+All databases (PostgreSQL, MySQL, and MSSQL) are started by default. Because the official MSSQL image supports only `amd64`, the MSSQL service and tests are automatically skipped on other platforms (e.g., `arm64`).
+
+When running tests repeatedly, backing database containers remain warm in the background for instant re-runs. To tear down the database services when finished:
+
+    $ ./docker.sh down
+
+### Option B: Running Natively on the Host
+
+Install dependencies and run the tests on your machine:
 
     $ mix deps.get
 
-Then run the basic test suite (no dependencies on the database) with:
+Run the basic test suite (without databases):
 
     $ mix test
 
-To run the test suite with tests that test a specific database, run:
+To run tests against a specific database:
 
     $ mix test --include database:postgresql
     $ mix test --include database:mysql
     $ mix test --include database:mssql
     $ mix test --include database:sqlite3
 
-For convenience, there is also a `docker-compose.yml` file that allows for starting up all of the supported databases locally.
-
-    $ docker-compose up
-
-This allows all tests to be run with the following command
+To run all tests including databases:
 
     $ mix test --include database
 
-Or alternatively, with docker and docker compose installed, you can just run `./docker.sh`.
+> [!NOTE]
+> **Running databases for host-native tests:**
+> `docker-compose.yml` does not publish database ports to the host by default. This avoids port collisions with local databases already running on your machine (e.g. PostgreSQL on 5432 or MySQL on 3306) and prevents exposing test databases with default credentials to the local network.
+>
+> When running tests directly on the host (`mix test`) rather than inside Docker (`./docker.sh`), include `docker-compose.ports.yml` to publish ports strictly to loopback (`127.0.0.1`):
+>
+> ```bash
+> # Start all databases with host ports published on 127.0.0.1
+> $ docker compose -f docker-compose.yml -f docker-compose.ports.yml up -d
+>
+> # Or start only a specific database (e.g. Postgres)
+> $ docker compose -f docker-compose.yml -f docker-compose.ports.yml up -d postgres
+> ```
 
 ## How tests are written