test: unify adapter tests into a shared Base and normalize adapter behavior

.github/workflows/tests-external.yml

@@ -31,8 +31,7 @@ jobs:
           TESTS_GITHUB_APP_IDENTIFIER: ${{ secrets.TESTS_GITHUB_APP_IDENTIFIER }}
           TESTS_GITHUB_INSTALLATION_ID: ${{ secrets.TESTS_GITHUB_INSTALLATION_ID }}
       run: |
-        docker compose --profile ${{ matrix.adapter }} up -d
-        sleep 15
+        docker compose --profile ${{ matrix.adapter }} up -d --wait --wait-timeout 900
 
     - name: Doctor
       run: |

.github/workflows/tests.yml

@@ -27,8 +27,7 @@ jobs:
           TESTS_GITHUB_APP_IDENTIFIER: ${{ secrets.TESTS_GITHUB_APP_IDENTIFIER }}
           TESTS_GITHUB_INSTALLATION_ID: ${{ secrets.TESTS_GITHUB_INSTALLATION_ID }}
       run: |
-        docker compose --profile ${{ matrix.adapter }} up -d
-        sleep 15
+        docker compose --profile ${{ matrix.adapter }} up -d --wait --wait-timeout 900
 
     - name: Doctor
       run: |

docker-compose.yml

@@ -218,10 +218,13 @@ services:
     ports:
       - "3003:80"
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost/-/health"]
+      # A single successful check only means nginx answered, not that the API
+      # underneath it can serve requests, so require 3 in a row before
+      # depends_on: condition: service_healthy (gitlab-bootstrap below) proceeds.
+      test: ["CMD-SHELL", "for i in 1 2 3; do curl -f http://localhost/-/health || exit 1; sleep 10; done"]
       interval: 30s
-      timeout: 10s
-      retries: 20
+      timeout: 45s
+      retries: 5
       start_period: 300s
     profiles:
       - gitlab

src/VCS/Adapter/Git.php

@@ -99,6 +99,9 @@ abstract public function createTag(string $owner, string $repositoryName, string
     /**
      * Get commit statuses
      *
+     * Every adapter reports each status as
+     * ['state' => string, 'description' => string, 'target_url' => string, 'context' => string].
+     *
      * @param string $owner Owner of the repository
      * @param string $repositoryName Name of the repository
      * @param string $commitHash SHA of the commit

src/VCS/Adapter/Git/GitHub.php

@@ -101,6 +101,12 @@ public function createRepository(string $owner, string $repositoryName, bool $pr
             'private' => $private,
         ]);
 
+        $responseHeaders = $response['headers'] ?? [];
+        $statusCode = $responseHeaders['status-code'] ?? 0;
+        if ($statusCode >= 400) {
+            throw new Exception("Creating repository {$repositoryName} failed with status code {$statusCode}", $statusCode);
+        }
+
         return $response['body'] ?? [];
     }
     /**
@@ -254,12 +260,21 @@ public function searchRepositories(string $owner, int $page, int $per_page, stri
                 'per_page' => $per_page,
                 'sort' => 'updated'
             ]);
-            $responseBody = $response['body'] ?? [];
+            $responseHeaders = $response['headers'] ?? [];
+            $statusCode = $responseHeaders['status-code'] ?? 0;
 
-            if (!array_key_exists('items', $responseBody)) {
-                throw new Exception("Repositories list missing in the response.");
+            // The search API rejects a query naming an owner that does not exist,
+            // which is a missing owner rather than a failure worth reporting.
+            if ($statusCode === 422) {
+                return ['items' => [], 'total' => 0];
+            }
+
+            if ($statusCode >= 400) {
+                throw new Exception("Failed to search repositories: HTTP {$statusCode}", $statusCode);
             }
 
+            $responseBody = $response['body'] ?? [];
+
             return [
                 'items' => $responseBody['items'] ?? [],
                 'total' => $responseBody['total_count'] ?? 0,
@@ -277,12 +292,14 @@ public function searchRepositories(string $owner, int $page, int $per_page, stri
                 'per_page' => $per_page,
             ]);
 
-            $responseBody = $response['body'] ?? [];
-
-            if (!array_key_exists('repositories', $responseBody)) {
-                throw new Exception("Repositories list missing in the response.");
+            $responseHeaders = $response['headers'] ?? [];
+            $statusCode = $responseHeaders['status-code'] ?? 0;
+            if ($statusCode >= 400) {
+                throw new Exception("Failed to list installation repositories: HTTP {$statusCode}", $statusCode);
             }
 
+            $responseBody = $response['body'] ?? [];
+
             return [
                 'items' => $responseBody['repositories'] ?? [],
                 'total' => $responseBody['total_count'] ?? 0,
@@ -297,12 +314,14 @@ public function searchRepositories(string $owner, int $page, int $per_page, stri
                 'per_page' => 100, // Maximum allowed by GitHub API
             ]);
 
-            $responseBody = $response['body'] ?? [];
-
-            if (!array_key_exists('repositories', $responseBody)) {
-                throw new Exception("Repositories list missing in the response.");
+            $responseHeaders = $response['headers'] ?? [];
+            $statusCode = $responseHeaders['status-code'] ?? 0;
+            if ($statusCode >= 400) {
+                throw new Exception("Failed to list installation repositories: HTTP {$statusCode}", $statusCode);
             }
 
+            $responseBody = $response['body'] ?? [];
+
             // Filter repositories to only include those that match the search query.
             $filteredRepositories = array_filter($responseBody['repositories'] ?? [], fn ($repo) => stripos($repo['name'] ?? '', $search) !== false);
 
@@ -984,7 +1003,12 @@ public function updateCommitStatus(string $repositoryName, string $commitHash, s
             'context' => $context,
         ];
 
-        $this->call(self::METHOD_POST, $url, ['Authorization' => "Bearer $this->accessToken"], $body);
+        $response = $this->call(self::METHOD_POST, $url, ['Authorization' => "Bearer $this->accessToken"], $body);
+        $responseHeaders = $response['headers'] ?? [];
+        $statusCode = $responseHeaders['status-code'] ?? 0;
+        if ($statusCode >= 400) {
+            throw new Exception("Failed to update commit status: HTTP {$statusCode}", $statusCode);
+        }
     }
 
     /**

src/VCS/Adapter/Git/GitLab.php

@@ -696,7 +696,8 @@ public function getUser(string $username): array
 
     public function getOwnerName(string $installationId, ?int $repositoryId = null): string
     {
-        if ($repositoryId !== null) {
+        // A missing or non-positive id means "no repository", same as on Gitea
+        if ($repositoryId !== null && $repositoryId > 0) {
             $url = "/projects/{$repositoryId}";
             $response = $this->call(self::METHOD_GET, $url, ['Authorization' => 'Bearer ' . $this->accessToken]);
             $responseHeaders = $response['headers'] ?? [];

src/VCS/Adapter/Git/Gitea.php

@@ -100,6 +100,12 @@ public function createRepository(string $owner, string $repositoryName, bool $pr
             'private' => $private,
         ]);
 
+        $responseHeaders = $response['headers'] ?? [];
+        $statusCode = $responseHeaders['status-code'] ?? 0;
+        if ($statusCode >= 400) {
+            throw new Exception("Creating repository {$repositoryName} failed with status code {$statusCode}", $statusCode);
+        }
+
         $result = $response['body'] ?? [];
         if (is_array($result)) {
             // Gitea's API does not expose `pushed_at`; surface `updated_at` under that key
@@ -1289,6 +1295,21 @@ public function getCommitStatuses(string $owner, string $repositoryName, string
             throw new Exception("Failed to get commit statuses: HTTP {$responseHeadersStatusCode}", $responseHeadersStatusCode);
         }
 
-        return $response['body'] ?? [];
+        $responseBody = $response['body'] ?? [];
+        if (!is_array($responseBody)) {
+            return [];
+        }
+
+        $statuses = [];
+        foreach ($responseBody as $status) {
+            $statuses[] = [
+                'state' => $status['status'] ?? '',
+                'description' => $status['description'] ?? '',
+                'target_url' => $status['target_url'] ?? '',
+                'context' => $status['context'] ?? '',
+            ];
+        }
+
+        return $statuses;
     }
 }

src/VCS/Adapter/Git/Gogs.php

@@ -55,6 +55,12 @@ public function createRepository(string $owner, string $repositoryName, bool $pr
             'readme' => 'Default',
         ]);
 
+        $responseHeaders = $response['headers'] ?? [];
+        $statusCode = $responseHeaders['status-code'] ?? 0;
+        if ($statusCode >= 400) {
+            throw new Exception("Creating repository {$repositoryName} failed with status code {$statusCode}", $statusCode);
+        }
+
         $result = $response['body'] ?? [];
         if (is_array($result)) {
             // Gogs' API does not expose `pushed_at`; surface `updated_at` under that key
@@ -491,6 +497,16 @@ public function getPullRequestFromBranch(string $owner, string $repositoryName,
         throw new Exception("Pull request API is not supported by Gogs");
     }
 
+    /**
+     * Get the files of a pull request
+     *
+     * @return array<mixed>
+     */
+    public function getPullRequestFiles(string $owner, string $repositoryName, int $pullRequestNumber): array
+    {
+        throw new Exception("Pull request API is not supported by Gogs");
+    }
+
     /**
      * Update commit status
      *

tests/VCS/Adapter/ForgejoTest.php

@@ -5,25 +5,19 @@
 use Utopia\Cache\Adapter\None;
 use Utopia\Cache\Cache;
 use Utopia\System\System;
-use Utopia\VCS\Adapter\Git;
 use Utopia\VCS\Adapter\Git\Forgejo;
 
 class ForgejoTest extends GiteaTest
 {
     protected static string $accessToken = '';
 
     protected static string $owner = '';
+    protected static string $avatarDomain = '/avatars/';
+    protected static string $eventHeader = 'x-forgejo-event';
+    protected static string $signatureHeader = 'x-forgejo-signature';
 
-    protected string $webhookEventHeader = 'X-Forgejo-Event';
-    protected string $webhookSignatureHeader = 'X-Forgejo-Signature';
-    protected string $avatarDomain = 'http://localhost:3000/avatars/';
 
-    protected function createVCSAdapter(): Git
-    {
-        return new Forgejo(new Cache(new None()));
-    }
-
-    public function setUp(): void
+    protected function setupAdapter(): void
     {
         if (empty(static::$accessToken)) {
             $this->setupForgejo();