Add Bitbucket adapter

.github/workflows/tests-external.yml

@@ -17,19 +17,35 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        adapter: [gitea, forgejo, github, gitlab, gogs]
+        adapter: [gitea, forgejo, github, gitlab, gogs, bitbucket]
 
     steps:
     - name: Check out the repo
       uses: actions/checkout@v4
       with:
         ref: ${{ github.event.pull_request.head.sha }}
 
+    - name: Check Bitbucket credential shape
+      if: matrix.adapter == 'bitbucket'
+      env:
+        TOKEN: ${{ secrets.TESTS_BITBUCKET_ACCESS_TOKEN }}
+      run: |
+        # Reports which auth scheme the adapter will pick, never the value
+        if [ -z "$TOKEN" ]; then
+          echo "TESTS_BITBUCKET_ACCESS_TOKEN is not set"
+        elif printf '%s' "$TOKEN" | grep -q ':'; then
+          echo "credential is email:token -> Basic (${#TOKEN} chars)"
+        else
+          echo "credential is a bare token -> Bearer (${#TOKEN} chars)"
+        fi
+
     - name: Start Test Stack
       env:
           TESTS_GITHUB_PRIVATE_KEY: ${{ secrets.TESTS_GITHUB_PRIVATE_KEY }}
           TESTS_GITHUB_APP_IDENTIFIER: ${{ secrets.TESTS_GITHUB_APP_IDENTIFIER }}
           TESTS_GITHUB_INSTALLATION_ID: ${{ secrets.TESTS_GITHUB_INSTALLATION_ID }}
+          TESTS_BITBUCKET_ACCESS_TOKEN: ${{ secrets.TESTS_BITBUCKET_ACCESS_TOKEN }}
+          TESTS_BITBUCKET_WORKSPACE: ${{ secrets.TESTS_BITBUCKET_WORKSPACE }}
       run: |
         docker compose --profile ${{ matrix.adapter }} up -d --wait --wait-timeout 900
 

.github/workflows/tests.yml

@@ -15,17 +15,33 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        adapter: [gitea, forgejo, github, gitlab, gogs]
+        adapter: [gitea, forgejo, github, gitlab, gogs, bitbucket]
 
     steps:
     - name: Check out the repo
       uses: actions/checkout@v4
 
+    - name: Check Bitbucket credential shape
+      if: matrix.adapter == 'bitbucket'
+      env:
+        TOKEN: ${{ secrets.TESTS_BITBUCKET_ACCESS_TOKEN }}
+      run: |
+        # Reports which auth scheme the adapter will pick, never the value
+        if [ -z "$TOKEN" ]; then
+          echo "TESTS_BITBUCKET_ACCESS_TOKEN is not set"
+        elif printf '%s' "$TOKEN" | grep -q ':'; then
+          echo "credential is email:token -> Basic (${#TOKEN} chars)"
+        else
+          echo "credential is a bare token -> Bearer (${#TOKEN} chars)"
+        fi
+
     - name: Start Test Stack
       env:
           TESTS_GITHUB_PRIVATE_KEY: ${{ secrets.TESTS_GITHUB_PRIVATE_KEY }}
           TESTS_GITHUB_APP_IDENTIFIER: ${{ secrets.TESTS_GITHUB_APP_IDENTIFIER }}
           TESTS_GITHUB_INSTALLATION_ID: ${{ secrets.TESTS_GITHUB_INSTALLATION_ID }}
+          TESTS_BITBUCKET_ACCESS_TOKEN: ${{ secrets.TESTS_BITBUCKET_ACCESS_TOKEN }}
+          TESTS_BITBUCKET_WORKSPACE: ${{ secrets.TESTS_BITBUCKET_WORKSPACE }}
       run: |
         docker compose --profile ${{ matrix.adapter }} up -d --wait --wait-timeout 900
 

CONTRIBUTING.md

@@ -88,7 +88,7 @@ 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`.
+Where `<adapter>` is one of: `gitea`, `forgejo`, `github`, `gitlab`, `gogs`, `bitbucket`.
 
 For example, to run Gitea tests:
 
@@ -100,6 +100,13 @@ docker compose exec -T tests vendor/bin/phpunit --configuration phpunit.xml --te
 
 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.
 
+The `bitbucket` adapter runs against Bitbucket Cloud, which has no self-hostable image, so it needs credentials instead of a local service:
+
+- `TESTS_BITBUCKET_ACCESS_TOKEN` — a credential with read and write access to repositories, pull requests and webhooks: either a bearer token (OAuth 2.0, workspace or repository) or an Atlassian account API token given as `email:token`
+- `TESTS_BITBUCKET_WORKSPACE` — workspace the test repositories are created in; defaults to the token owner's own workspace
+
+The workspace needs at least one project, since Bitbucket assigns every new repository to one. Without these variables the suite is skipped, the same way the `github` one is.
+
 ## 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

@@ -14,6 +14,8 @@ services:
       - TESTS_GITHUB_PRIVATE_KEY
       - TESTS_GITHUB_APP_IDENTIFIER
       - TESTS_GITHUB_INSTALLATION_ID
+      - TESTS_BITBUCKET_ACCESS_TOKEN
+      - TESTS_BITBUCKET_WORKSPACE
       - TESTS_GITEA_URL=http://gitea:3000
       - TESTS_REQUEST_CATCHER_URL=http://request-catcher:5000
       - TESTS_FORGEJO_URL=http://forgejo:3000

docs/add-new-vcs-adapter.md

@@ -76,6 +76,23 @@ $vcs->initializeVariables($installationId, $privateKey, $appId);
 
 Only include dependencies strictly necessary for the adapter, preferably official PHP libraries, if available.
 
+#### Webhook deliveries describing more than one event
+
+`getEvent()` returns the single event a payload describes, which is all most
+providers ever send. A provider that batches several refs into one delivery
+should override `getEvents()` as well, so a consumer can read all of them:
+
+```php
+public function getEvents(string $event, string $payload): array
+{
+    // one entry per ref the delivery touched
+}
+```
+
+The default `getEvents()` wraps `getEvent()`, so an adapter that never batches
+needs no override. Consumers that must not miss a ref should call `getEvents()`
+rather than `getEvent()` — the latter reports only the first event of a batch.
+
 ### Testing with Docker 🛠️
 
 The existing test suite is helpful when developing a new VCS adapter. Use official Docker images from trusted sources. Add new tests for your new VCS adapter in `tests/VCS/Adapter/VCSTest.php` test class. The specific `docker-compose` command for testing can be found in the [README](/README.md#tests).

phpunit.xml

@@ -24,5 +24,8 @@
         <testsuite name="gogs">
             <file>./tests/VCS/Adapter/GogsTest.php</file>
         </testsuite>
+        <testsuite name="bitbucket">
+            <file>./tests/VCS/Adapter/BitbucketTest.php</file>
+        </testsuite>
     </testsuites>
 </phpunit>

src/VCS/Adapter.php

@@ -224,6 +224,26 @@ public function validateWebhookEvent(string $payload, string $signature, string
      */
     abstract public function getEvent(string $event, string $payload): array;
 
+    /**
+     * Parses a webhook payload into every event it describes.
+     *
+     * Default wraps getEvent(), the one event every provider's payload can
+     * describe. Override for a provider whose payload can batch several (e.g.
+     * Bitbucket, which reports every ref a push touched in one delivery).
+     *
+     * @param string $event Type of event: push, pull_request etc
+     * @param string $payload The webhook payload received from Git provider
+     * @return array<array<mixed>> Parsed payloads as json objects
+     */
+    public function getEvents(string $event, string $payload): array
+    {
+        $parsed = $this->getEvent($event, $payload);
+
+        // An event the adapter doesn't report describes nothing, so report
+        // nothing rather than one empty event
+        return $parsed === [] ? [] : [$parsed];
+    }
+
     /**
      * HTTP header name carrying the webhook event type (e.g. 'x-github-event').
      */

src/VCS/Adapter/Git.php

@@ -80,9 +80,11 @@ abstract public function createPullRequest(string $owner, string $repositoryName
      * @param string $url Webhook URL to send events to
      * @param string $secret Webhook secret for signature validation
      * @param array<string> $events Events to trigger the webhook
-     * @return int Webhook ID
+     * @return int|string Webhook ID, as the provider identifies it: an int on
+     *                    the providers that number their hooks, a string where
+     *                    they don't (Bitbucket identifies them by UUID)
      */
-    abstract public function createWebhook(string $owner, string $repositoryName, string $url, string $secret, array $events = ['push', 'pull_request']): int;
+    abstract public function createWebhook(string $owner, string $repositoryName, string $url, string $secret, array $events = ['push', 'pull_request']): int|string;
 
 
     /**