⚠️ Warning:
This integration setup is for Atlassian Bitbucket Cloud, not for On Premise, Server or Data center. If your set-up is not Cloud, please consult our Atlassian Application Tunnel Documentation
1. How does SQAI Suite Leverage This Integration?
Connecting to Bitbucket allows SQAI to integrate directly into your development workflow, transforming test cases into executable automation code:
Context-Aware Scripting: SQAI reads your existing codebase, framework conventions, and folder structure within the repository to generate high-quality, maintainable automation scripts that match your team's standards.
Direct Code Delivery: Allows SQAI to push generated automation code (e.g., Playwright or Selenium scripts) directly to a unique branch in your repository, ready for review and execution.
Version Control & Traceability: Ensures all generated code is immediately part of your version control history, linking back to the original test case.
2. Information Required from Your Bitbucket Account
To establish a secure, plug-and-play connection, we need three pieces of information, all of which can be quickly extracted from a repository URL, plus a secure Access Token.
⚠️ The required information is extracted from a URL structure like this:
https://bitbucket.org/{YOUR_WORKSPACE}/{YOUR_REPO_NAME}
Required Detail | How to Find It in the URL | Example Value |
Workspace | The first segment after |
|
Repo Name | The second segment (the name of the specific repository). |
|
Access Token | Must be generated securely (See Section 3) |
|
3. Setting up the Integration
The most crucial step is generating a dedicated Repository Access Token with the correct scope for reading code context and pushing new scripts.
🔑 Permission Requirements
The user generating the token must have the necessary permissions to clone, read, and push code to the repository.
Step 1: Navigate to Workspace or Repository Settings
The difference between Workspace and Repository (Repo) Level Settings determines the scope of control and the access tokens you create.
Here is a breakdown of the differences:
Feature | Workspace Level | Repository (Repo) Level |
Definition / Scope | The highest level of organization in Bitbucket. A workspace holds one or more projects and repositories. | The lowest level of organization. It contains the actual code and branches for a single project/application. |
Settings Type | Settings that apply to ALL repositories and projects within that workspace (e.g., billing, integrations, default permissions). | Settings that apply ONLY to the specific repository (e.g., branch restrictions, access keys for that single repo). |
Access Tokens | Workspace Access Tokens: Grant permissions across all repositories within the entire workspace. | Repository Access Tokens (Recommended for SQAI): Grant permissions only to a single, specific repository. |
Example Use Case | Used for global tools or administrators who need to manage multiple Repositories at once. | Used for only a specific repository where the code needs to be pushed. |
In Bitbucket, navigate to your specific repository and click Workspace or Repository settings (often found near the bottom of the left navigation menu).
Workspace Acces Token:
Repository Acces Token:
Step 2: Create Workspace or Repository Access Token
Under settings, select Access Tokens, and then click Create Access Token.
Step 3: Set Access Token Scopes
When creating the token, ensure you set the following minimal scopes:
Category | Required Scope Setting |
Repositories | Read & Write (Allows SQAI to read existing code for context and write/push new scripts.) |
Pull Requests | Read & Write (Allows SQAI to create the PR for your team's review.) |
❌IMPORTANT:
Do not forget to check the scopes before continuing
Step 4: Secure Token
Immediately copy and secure the generated Access Token. Bitbucket will not display this token again.
4. Entering Details in SQAI Suite
Once you have secured your Access Token and gathered your Workspace and Repo details, you can complete the setup in the SQAI Suite platform.
Step 1: Navigate to Integrations Go to your SQAI Suite settings and select the Integrations page. Find and select the Atlassian Bitbucket configuration.
Step 2: Enter Details Insert the following details into the corresponding fields shown on the configuration page:
Configuration Field Name | Value to Enter | Notes |
API key | The Repository Access Token generated in Section 3. | SQAI refers to this token as the 'API key'. |
Expiration Date | Optional. Date the token expires. SQAI will alert you prior to expiration. |
|
Base URL / API URL | Default values. Only change if using an on-premise installation. Before continuing with an on-premise installation, please consult the Atlassian Application Tunnel Requirements. | For Bitbucket Cloud, these should remain untouched. |
Base branch | The default branch of your repository (e.g., | Used by SQAI for referencing existing code structure, so we encourage stable branches as a best practice. |
Bitbucket Workspace | The Workspace name extracted from your URL (See Section 2). |
|
Bitbucket Repository | The Repo Name extracted from your URL (See Section 2). |
|
Token Scope | REPO | This confirms you are using the more secure Repository-level scope (as recommended in Section 3). |
Step 3: Save and Confirm Click "Save Configuration." If the set-up is successful, you will receive a success message and see a green indicator next to your Bitbucket integration.
5. Troubleshooting Your Bitbucket Integration
If SQAI reports an error or fails to connect, use this checklist to quickly identify and resolve the most common issues related to repository access.
Problem | Cause | Solution |
Connection Failed: "Unauthorized" or "Access Denied" | A. Incorrect Token Scope: The Repository Access Token is missing the required Read & Write permission for the Repositories or Pull Requests scopes. | Verify Token Scopes: Go to Repository Settings > Access Tokens and ensure the active token includes Repositories: Read & Write and Pull Requests: Read & Write. |
Invalid Resource: Cannot Find Repo | B. Incorrect Name/Typo: The Workspace or Repository Name entered contains a typo. | Double-Check URL: Verify the names are entered exactly as they appear in the Bitbucket URL (names are often case-sensitive). |
SQAI Simply Does Not Connect | C. IP Restriction/VPN: While Bitbucket Cloud is public, custom firewall rules or network settings may prevent the push. | Check Network: If you encounter push errors, ensure there are no proxy settings or internal network security groups blocking external repository activity. |
Token Expired | D. Token Expiration: Access Tokens are set to expire after a certain period (default is often 30 days). | Generate New Token: The original user must create a new token with the required scopes and update the configuration in SQAI Suite. |