Add config example, changeset and API reports

Signed-off-by: Jake Smith <jakemgsmith@gmail.com>

.changeset/dark-dingos-see.md

@@ -0,0 +1,27 @@
+---
+'@backstage/plugin-scaffolder-backend-module-bitbucket-cloud': minor
+'@backstage/plugin-bitbucket-cloud-common': patch
+'@backstage/integration': minor
+'@backstage/backend-defaults': patch
+---
+
+Added support for Bitbucket Cloud OAuth. This introduces an alternative authentication method using a workspace OAuth consumer, alongside App Passwords (deprecated) and API tokens. OAuth does not require a bot or service account and avoids token expiry issues.
+
+**BREAKING CHANGES**
+
+- **@backstage/integration** (`src/bitbucketCloud/core.ts`)
+
+  - `getBitbucketCloudRequestOptions` now returns a `Promise` and **must** be awaited.
+
+- **@backstage/plugin-scaffolder-backend-module-bitbucket-cloud** (`src/actions/helpers.ts`)
+  - `getBitbucketClient` now returns a `Promise` and **must** be awaited.
+  - `getAuthorizationHeader` now returns a `Promise` and **must** be awaited.
+
+**OAuth usage example**
+
+```yaml
+integrations:
+  bitbucketCloud:
+    - clientId: client-id
+      clientSecret: client-secret
+```

app-config.yaml

@@ -109,8 +109,12 @@ integrations:
       token: ${GITLAB_TOKEN}
   ### Example for how to add a bitbucket cloud integration
   # bitbucketCloud:
+  #   # Using API token
   #   - username: ${BITBUCKET_USERNAME}
   #     token: ${BITBUCKET_API_TOKEN}
+  #   # Using OAuth
+  #   - clientId: ${BITBUCKET_CLIENT_ID}
+  #     clientSecret: ${BITBUCKET_CLIENT_SECRET}
   ### Example for how to add your bitbucket server instance using the API:
   # - host: server.bitbucket.com
   #   apiBaseUrl: server.bitbucket.com

packages/integration/report.api.md

@@ -250,6 +250,8 @@ export type BitbucketCloudIntegrationConfig = {
   username?: string;
   appPassword?: string;
   token?: string;
+  clientId?: string;
+  clientSecret?: string;
   commitSigningKey?: string;
 };
 
@@ -450,12 +452,18 @@ export function getBitbucketCloudFileFetchUrl(
   config: BitbucketCloudIntegrationConfig,
 ): string;
 
+// @public
+export function getBitbucketCloudOAuthToken(
+  clientId: string,
+  clientSecret: string,
+): Promise<string>;
+
 // @public
 export function getBitbucketCloudRequestOptions(
   config: BitbucketCloudIntegrationConfig,
-): {
+): Promise<{
   headers: Record<string, string>;
-};
+}>;
 
 // @public @deprecated
 export function getBitbucketDefaultBranch(

plugins/scaffolder-backend-module-bitbucket-cloud/report.api.md

@@ -25,12 +25,6 @@ export const createBitbucketPipelinesRunAction: (options: {
             | {
                 type?: string | undefined;
                 source?: string | undefined;
-                selector?:
-                  | {
-                      type: string;
-                      pattern: string;
-                    }
-                  | undefined;
                 pull_request?:
                   | {
                       id: string;
@@ -45,6 +39,12 @@ export const createBitbucketPipelinesRunAction: (options: {
                 destination?: string | undefined;
                 ref_name?: string | undefined;
                 ref_type?: string | undefined;
+                selector?:
+                  | {
+                      type: string;
+                      pattern: string;
+                    }
+                  | undefined;
                 destination_commit?:
                   | {
                       hash: string;