updated with some indentation fix in docker-compose + contributermd file and brought changes done in the old pr by matej

Author: jaysomani

.github/workflows/tests-external.yml

@@ -9,11 +9,16 @@ permissions:
 
 jobs:
   tests:
-    name: Tests (External)
+    name: ${{ matrix.adapter }}
     runs-on: ubuntu-latest
 
     if: github.event.label.name == 'test'
 
+    strategy:
+      fail-fast: false
+      matrix:
+        adapter: [gitea, forgejo, github, gitlab, gogs]
+
     steps:
     - name: Check out the repo
       uses: actions/checkout@v4
@@ -26,15 +31,15 @@ jobs:
           TESTS_GITHUB_APP_IDENTIFIER: ${{ secrets.TESTS_GITHUB_APP_IDENTIFIER }}
           TESTS_GITHUB_INSTALLATION_ID: ${{ secrets.TESTS_GITHUB_INSTALLATION_ID }}
       run: |
-        docker compose up -d
+        docker compose --profile ${{ matrix.adapter }} up -d
         sleep 15
 
     - name: Doctor
       run: |
-        docker compose logs
+        docker compose --profile ${{ matrix.adapter }} logs
         docker ps
         docker network ls
 
     - name: Run Tests
       run: |
-        docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml tests
+        docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml --testsuite ${{ matrix.adapter }}

.github/workflows/tests.yml

@@ -8,10 +8,15 @@ permissions:
 
 jobs:
   tests:
-    name: Tests
+    name: ${{ matrix.adapter }}
     runs-on: ubuntu-latest
     if: github.event.pull_request.head.repo.full_name == github.repository
 
+    strategy:
+      fail-fast: false
+      matrix:
+        adapter: [gitea, forgejo, github, gitlab, gogs]
+
     steps:
     - name: Check out the repo
       uses: actions/checkout@v4
@@ -22,15 +27,15 @@ jobs:
           TESTS_GITHUB_APP_IDENTIFIER: ${{ secrets.TESTS_GITHUB_APP_IDENTIFIER }}
           TESTS_GITHUB_INSTALLATION_ID: ${{ secrets.TESTS_GITHUB_INSTALLATION_ID }}
       run: |
-        docker compose up -d
+        docker compose --profile ${{ matrix.adapter }} up -d
         sleep 15
 
     - name: Doctor
       run: |
-        docker compose logs
+        docker compose --profile ${{ matrix.adapter }} logs
         docker ps
         docker network ls
 
     - name: Run Tests
       run: |
-        docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml tests
+        docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml --testsuite ${{ matrix.adapter }}

CONTRIBUTING.md

@@ -76,6 +76,30 @@ This will allow the Utopia-php community to have sufficient discussion about the
 
 This is also important for the Utopia-php lead developers to be able to give technical input and different emphasis regarding the feature design and architecture. Some bigger features might need to go through our [RFC process](https://github.com/appwrite/rfc).
 
+## Running Tests
+
+Tests are split by adapter. Each adapter has its own Docker Compose profile and PHPUnit test suite.
+
+To start the stack and run tests for a specific adapter:
+
+```bash
+docker compose --profile <adapter> up -d
+sleep 15
+docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml --testsuite <adapter>
+```
+
+Where `<adapter>` is one of: `gitea`, `forgejo`, `github`, `gitlab`, `gogs`.
+
+For example, to run Gitea tests:
+
+```bash
+docker compose --profile gitea up -d
+sleep 15
+docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml --testsuite gitea
+```
+
+The `github` adapter does not require any local services — only the GitHub secrets (`TESTS_GITHUB_PRIVATE_KEY`, `TESTS_GITHUB_APP_IDENTIFIER`, `TESTS_GITHUB_INSTALLATION_ID`) as environment variables.
+
 ## Adding A New Adapter
 
 You can follow our [Adding new VCS Adapter](docs/add-new-vcs-adapter.md) tutorial to add a new VCS adapter like GitLab, Bitbucket etc. in this library.

docker-compose.yml

@@ -21,23 +21,32 @@ services:
       - TESTS_GITLAB_URL=http://gitlab:80
     depends_on:
       gitea:
-        condition: service_healthy
+        condition: service_started
+        required: false
       gitea-bootstrap:
         condition: service_completed_successfully
+        required: false
       forgejo:
-        condition: service_healthy
+        condition: service_started
+        required: false
       forgejo-bootstrap:
         condition: service_completed_successfully
+        required: false
       gogs:
-        condition: service_healthy
+        condition: service_started
+        required: false
       gogs-bootstrap:
         condition: service_completed_successfully
+        required: false
       gitlab:
-        condition: service_healthy
+        condition: service_started
+        required: false
       gitlab-bootstrap:
         condition: service_completed_successfully
+        required: false
       request-catcher:                                               
         condition: service_started
+        required: false
 
   gitea:
     image: gitea/gitea:1.21.5
@@ -46,7 +55,7 @@ services:
       - USER_GID=1000
       - GITEA__database__DB_TYPE=sqlite3
       - GITEA__security__INSTALL_LOCK=true
-      - GITEA__webhook__ALLOWED_HOST_LIST=*        
+      - GITEA__webhook__ALLOWED_HOST_LIST=*
       - GITEA__webhook__SKIP_TLS_VERIFY=true
       - GITEA__webhook__DELIVER_TIMEOUT=10
       - GITEA__server__LOCAL_ROOT_URL=http://gitea:3000/
@@ -60,6 +69,8 @@ services:
       timeout: 5s
       retries: 10
       start_period: 10s
+    profiles:
+      - gitea
 
   gitea-bootstrap:
     image: gitea/gitea:1.21.5
@@ -68,6 +79,7 @@ services:
     depends_on:
       gitea:
         condition: service_healthy
+        required: false
     entrypoint: /bin/sh
     environment:
       - GITEA_ADMIN_USERNAME=${GITEA_ADMIN_USERNAME:-utopia}
@@ -81,10 +93,16 @@ services:
           echo $$TOKEN > /data/gitea/token.txt;
         fi
       "
+    profiles:
+      - gitea
   request-catcher:                                                   
     image: appwrite/requestcatcher:1.1.0
     ports:
       - "5000:5000"
+    profiles:
+      - gitea
+      - forgejo
+      - gogs
 
   forgejo:
     image: codeberg.org/forgejo/forgejo:9
@@ -105,6 +123,8 @@ services:
       timeout: 5s
       retries: 10
       start_period: 10s
+    profiles:
+      - forgejo
 
   forgejo-bootstrap:
     image: codeberg.org/forgejo/forgejo:9
@@ -113,6 +133,7 @@ services:
     depends_on:
       forgejo:
         condition: service_healthy
+        required: false
     entrypoint: /bin/sh
     environment:
       - FORGEJO_ADMIN_USERNAME=${FORGEJO_ADMIN_USERNAME:-utopia}
@@ -126,6 +147,8 @@ services:
           echo $$TOKEN > /data/gitea/token.txt;
         fi
       "
+    profiles:
+      - forgejo
 
   gogs:
     image: gogs/gogs:0.14
@@ -140,6 +163,8 @@ services:
       timeout: 5s
       retries: 10
       start_period: 15s
+    profiles:
+      - gogs
 
   gogs-bootstrap:
     image: gogs/gogs:0.14
@@ -149,6 +174,7 @@ services:
     depends_on:
       gogs:
         condition: service_healthy
+        required: false
     entrypoint: /bin/sh
     environment:
       - GOGS_ADMIN_USERNAME=${GOGS_ADMIN_USERNAME:-utopia}
@@ -177,6 +203,8 @@ services:
           mkdir -p /data/gogs
           echo $$TOKEN > /data/gogs/token.txt
         fi
+    profiles:
+      - gogs
 
   gitlab:
     image: gitlab/gitlab-ce:18.10.1-ce.0
@@ -194,6 +222,8 @@ services:
       timeout: 10s
       retries: 20
       start_period: 300s
+    profiles:
+      - gitlab
 
   gitlab-bootstrap:
     image: alpine/curl:8.12.1
@@ -248,6 +278,8 @@ services:
           -H "Content-Type: application/json" \
           -d '{"allow_local_requests_from_web_hooks_and_services":true,"allow_local_requests_from_system_hooks":true}'
         echo "Local webhook requests enabled"
+    profiles:
+      - gitlab
 
 volumes:
   gitea-data:

phpunit.xml

@@ -9,8 +9,20 @@
          stopOnFailure="false"
         >
     <testsuites>
-        <testsuite name="Application Test Suite">
-            <directory>./tests/</directory>
+        <testsuite name="gitea">
+            <file>./tests/VCS/Adapter/GiteaTest.php</file>
+        </testsuite>
+        <testsuite name="forgejo">
+            <file>./tests/VCS/Adapter/ForgejoTest.php</file>
+        </testsuite>
+        <testsuite name="github">
+            <file>./tests/VCS/Adapter/GitHubTest.php</file>
+        </testsuite>
+        <testsuite name="gitlab">
+            <file>./tests/VCS/Adapter/GitLabTest.php</file>
+        </testsuite>
+        <testsuite name="gogs">
+            <file>./tests/VCS/Adapter/GogsTest.php</file>
         </testsuite>
     </testsuites>
 </phpunit>

src/VCS/Adapter/Git/Gitea.php

@@ -100,8 +100,14 @@ public function createRepository(string $owner, string $repositoryName, bool $pr
             'private' => $private,
         ]);
 
-        return $response['body'] ?? [];
-        // return is_array($body) ? $body : [];
+        $result = $response['body'] ?? [];
+        if (is_array($result)) {
+            // Gitea's API does not expose `pushed_at`; surface `updated_at` under that key
+            // for parity with the other VCS adapters (GitHub, GitLab).
+            $result['pushed_at'] = $result['pushed_at'] ?? ($result['updated_at'] ?? '');
+        }
+        return is_array($result) ? $result : [];
+        ;
     }
 
     public function createOrganization(string $orgName): string
@@ -207,6 +213,13 @@ public function searchRepositories(string $owner, int $page, int $per_page, stri
         $offset = ($page - 1) * $per_page;
         $pagedRepos = array_slice($filteredRepos, $offset, $per_page);
 
+        foreach ($pagedRepos as &$repo) {
+            if (is_array($repo)) {
+                $repo['pushed_at'] = $repo['pushed_at'] ?? ($repo['updated_at'] ?? '');
+            }
+        }
+        unset($repo);
+
         return [
             'items' => $pagedRepos,
             'total' => $total,
@@ -241,7 +254,11 @@ public function getRepository(string $owner, string $repositoryName): array
             throw new RepositoryNotFound("Repository not found");
         }
 
-        return $response['body'] ?? [];
+        $result = $response['body'] ?? [];
+        if (is_array($result)) {
+            $result['pushed_at'] = $result['pushed_at'] ?? ($result['updated_at'] ?? '');
+        }
+        return is_array($result) ? $result : [];
     }
 
     public function getRepositoryName(string $repositoryId): string
@@ -724,7 +741,7 @@ public function listBranches(string $owner, string $repositoryName): array
         for ($currentPage = 1; $currentPage <= $maxPages; $currentPage++) {
             $url = "/repos/{$owner}/{$repositoryName}/branches?page={$currentPage}&limit={$perPage}";
 
-            $response = $this->call(self::METHOD_GET, $url, ['Authorization' => "token $this->accessToken"]);
+            $response = $this->call(self::METHOD_GET, $url, ['Authorization' => "token $this->accessToken"], decode: false);
 
             $responseHeaders = $response['headers'] ?? [];
             $responseHeadersStatusCode = $responseHeaders['status-code'] ?? 0;
@@ -740,7 +757,7 @@ public function listBranches(string $owner, string $repositoryName): array
                 break;
             }
 
-            $responseBody = $response['body'] ?? [];
+            $responseBody = \json_decode($response['body'] ?? '', true);
 
             if (!is_array($responseBody)) {
                 break;
@@ -896,6 +913,9 @@ public function updateCommitStatus(string $repositoryName, string $commitHash, s
          */
     public function generateCloneCommand(string $owner, string $repositoryName, string $version, string $versionType, string $directory, string $rootDirectory): string
     {
+        if (empty($rootDirectory)) {
+            $rootDirectory = '*';
+        }
         $cloneUrl = "{$this->giteaUrl}/{$owner}/{$repositoryName}";
         if (!empty($this->accessToken)) {
             $cloneUrl = str_replace('://', "://{$owner}:{$this->accessToken}@", $this->giteaUrl) . "/{$owner}/{$repositoryName}";

src/VCS/Adapter/Git/Gogs.php

@@ -40,7 +40,13 @@ public function createRepository(string $owner, string $repositoryName, bool $pr
             'readme' => 'Default',
         ]);
 
-        return $response['body'] ?? [];
+        $result = $response['body'] ?? [];
+        if (is_array($result)) {
+            // Gogs' API does not expose `pushed_at`; surface `updated_at` under that key
+            // for parity with the other VCS adapters (GitHub, GitLab).
+            $result['pushed_at'] = $result['pushed_at'] ?? ($result['updated_at'] ?? '');
+        }
+        return is_array($result) ? $result : [];
     }
 
     /**
@@ -88,6 +94,15 @@ public function searchRepositories(string $owner, int $page, int $per_page, stri
         $offset = ($page - 1) * $per_page;
         $pagedRepos = array_slice($responseBody, $offset, $per_page);
 
+        // Gogs' API does not expose `pushed_at`; surface `updated_at` under that key
+        // for parity with the other VCS adapters (GitHub, GitLab).
+        foreach ($pagedRepos as &$repo) {
+            if (is_array($repo)) {
+                $repo['pushed_at'] = $repo['pushed_at'] ?? ($repo['updated_at'] ?? '');
+            }
+        }
+        unset($repo);
+
         return [
             'items' => $pagedRepos,
             'total' => $total,