Bitbucket

1. Overview

Bitbucket is a Git-based source code repository hosting service owned by Atlassian. It provides distributed version control and allows for collaboration on code projects, offering features like code review, pull requests, and CI/CD pipelines.

With the GoInsight Bitbucket node, you can automate your development and code management workflows. This integration allows you to programmatically interact with your Bitbucket account to manage the entire lifecycle of your software projects, including:

• Repository Management: Create, retrieve, update, and delete repositories.
• Code and Branching: Manage branches, tags, commits, and file contents within your repositories.
• Collaboration: Automate the creation and management of pull requests and comments.
• Project Organization: Handle projects and workspaces to structure your development efforts.
• CI/CD Integration: Create and monitor commit build statuses to integrate with your continuous integration pipelines.

2. Prerequisites

Before using this node, you must have a valid Bitbucket account. You will also need to generate an App Password with the necessary permissions (e.g., repository read/write, project administration) to authenticate your requests.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides a comprehensive set of operations for managing various Bitbucket resources, from high-level workspaces and projects down to individual commits and comments. The table below summarizes the available actions, grouped by the resource they operate on.

Operation Details

Create a Branch

Creates a new branch in a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• BranchName: Name of the new branch to be created.

Options:

• SourceBranch: Name of the source branch. Defaults to "master".

Output:

• Branch (object): Branch data created in Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Branch

Deletes a specific branch from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• BranchName: Name of the branch to be deleted.

Output:

• Deleted (bool): Indicates whether the branch was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Branches

Gets branches from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.

Options:

• Query: Query string for filtering tags.
• Sort: Sort order for tags.

Output:

• Branches (object-array): List of branch data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Branch

Gets a branch from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• BranchName: Name of the branch to be retrieved.

Output:

• Branch (object): Dictionary of branch data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Commit

Creates a new commit in a specified repository in Bitbucket by uploading files using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• Files: Dictionary where keys are file paths in repo and values are file contents.

Options:

• Message: Commit message. Defaults to "New commit".
• Branch: Branch name to commit to. Defaults to "master".

Output:

• Created (bool): True if commit was created successfully, False otherwise.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Commits

Gets commits from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.

Options:

• IncludeBranch: Branch name to include from commits.
• ExcludeBranch: Branch name to exclude from commits.
• Path: Path within the repository to get commits from.

Output:

• Commits (object-array): List of commit data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Commit

Gets a commit from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Hash of the commit to retrieve.

Output:

• Commit (object): Dictionary of commit data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Commit Comment

Creates a new comment on the specified commit in a Bitbucket repository using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Hash of the commit to add comment to.
• Content: Content of the comment to be created.

Output:

• Comment (object): Comment data created in Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Commit Comment

Deletes a specified commit comment for a workspace from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Hash of the commit the comment belongs to.
• CommentId: ID of the comment to delete.

Output:

• Deleted (bool): Indicates whether the comment was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Commit Comments

Gets comments for a commit from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Hash of the commit to retrieve comments for.

Options:

• Query: Query string for filtering comments.
• Sort: Sort order for comments.

Output:

• Comments (object-array): List of comment data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Commit Comment

Gets a specified commit comment from a Bitbucket repository using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Hash of the commit the comment belongs to.
• CommentId: ID of the comment to retrieve.

Output:

• Comment (object): Dictionary of comment data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Commit Comment

Updates the contents of a comment in a Bitbucket repository using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Hash of the commit the comment belongs to.
• CommentId: ID of the comment to update.
• Content: New content for the comment.

Output:

• Comment (object): Updated comment data from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create Commit Status

Creates a new build status for a commit in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Commit hash to create status for.
• Key: A unique key for the build status.
• State: The state of the build status. Valid values: SUCCESSFUL, FAILED, INPROGRESS.
• Url: Optional. A URL linking to the build result.

Options:

• Description: Optional. A description of the build status.
• Name: Optional. A name for the build status.

Output:

• Status (object): Details of the created commit status.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Commit Statuses

Gets all statuses (e.g. build results) for a specific commit from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Commit hash to get statuses for.

Output:

• Statuses (object-array): List of commit statuses retrieved from Bitbucket.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Commit Status

Gets the specified build status for a commit from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Commit hash to get status for.
• Key: The unique key of the build status to retrieve.

Output:

• Status (object): Details of the retrieved commit status.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update Commit Status

Updates the current status of a build status object on the specific commit for a commit from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• CommitHash: Commit hash to update status for.
• Key: A unique key for the build status.
• State: The state of the build status. Valid values: SUCCESSFUL, FAILED, INPROGRESS.
• Url: Optional. A URL linking to the build result.

Options:

• Description: A description of the build status.
• Name: Optional. A name for the build status.

Output:

• Status (object): Details of the updated commit status.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Directory Contents

Gets the contents of a directory at a specified revision for a workspace from Bitbucket.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• Path: Path to the directory in the repository.

Options:

• Branch: Branch name, commit hash or tag name. Defaults to "master".

Output:

• Directories (object-array): List of directory retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a File Commits

Gets a paginated list of commits that modified the specified file from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• FilePath: Path to the file within the repository.

Options:

• Commit: Commit SHA, branch name or tag name. Defaults to "master".

Output:

• Commits (object-array): Array of commit data that modified the specified file.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a File Contents

Gets the contents of a single file at a specified revision for a workspace from Bitbucket.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• FilePath: Path to the file in the repository.

Options:

• Branch: Branch name, commit hash or tag name. Defaults to "master".

Output:

• FileContent (string): if False, Content of file retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a File or Directory Property

Gets the property of a single file or a directory at a specified revision for a workspace from Bitbucket.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• FilePath: Path to the file in the repository.

Options:

• Branch: Branch name, commit hash or tag name. Defaults to "master".

Output:

• Property (object): if True, Metadata about the file retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Project

Creates a project in a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• ProjectKey: Project key/identifier.
• ProjectName: Project name.

Options:

• Description: Project description.

Output:

• Project (object): Project data created in Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Project

Deletes a specific project from a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• ProjectKey: Project key/name.

Output:

• Deleted (bool): Indicates whether the project was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Projects

Gets the list of projects in a specific workspace from Bitbucket using API token authentication.

Input Parameters:

• WorkspaceSlug: Workspace slug/name.

Output:

• Projects (object-array): List of projects retrieved from Bitbucket.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Project

Gets a specific project from a workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• ProjectKey: Project key/identifier.

Output:

• Project (object): Project data retrieved from Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Project

Updates a project in a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• ProjectKey: Project key/identifier to be updated.
• Name: New name for the project.
• Description: New description for the project.

Options:

• IsPrivate: Whether the project should be private.

Output:

• Project (object): Updated project data from Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Pull Request

Creates a new pull request in a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• Title: Title of the new pull request to be created.
• SourceBranch: Name of the source branch for the pull request.
• Description: Description of the pull request. Defaults to "".

Options:

• DestinationBranch: Name of the destination branch for the pull request. Defaults to "master".

Output:

• PullRequest (object): Pull request data created in Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Pull Requests

Gets many pull requests from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.

Output:

• PullRequests (object-array): Array object of pull requests data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Pull Request

Gets a pull request from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug.
• PullRequestId: Pull request ID.

Output:

• PullRequest (object): Pull request data retrieved from Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Pull Request

Updates an existing pull request in a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• PullRequestId: ID of the pull request to update.

Options:

• Title: New title for the pull request.
• SourceBranch: New source branch for the pull request.
• DestinationBranch: New destination branch for the pull request.
• Description: New description for the pull request.
• State: New state for the pull request (e.g., "OPEN", "DECLINED").

Output:

• PullRequest (object): Updated pull request data from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Repository

Creates a new repository in a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name to be created.

Options:

• ProjectKey: Project key for the repository. Defaults to "".
• IsPrivate: Whether the repository should be private. Defaults to False.

Output:

• Repository (object): Repository data created in Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Repository

Deletes a specific repository from a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.

Output:

• Deleted (bool): Indicates whether the repository was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Repository

Gets a specific repository from a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.

Output:

• Repository (object): Repository data retrieved from Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Repository

Updates a repository in a specified workspace in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name to be updated.
• Website: The repository's website.
• Description: New description for the repository.

Options:

• IsPrivate: Whether the repository should be private.

Output:

• Repository (object): Updated repository data from Bitbucket workspace.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Tag

Creates a new tag in a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• TagName: Name of the new tag to be created.
• Message: Message for annotated tag.

Options:

• TargetCommit: Target commit hash, branch name or tag name. Defaults to "master".

Output:

• Tag (object): Tag data created in Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Tag

Deletes a specific tag from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• TagName: Name of the tag to be deleted.

Output:

• Deleted (bool): Indicates whether the tag was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Tags

Gets tags from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.

Options:

• Query: Query string for filtering tags.
• Sort: Sort order for tags.

Output:

• Tags (object-array): List of tag data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Tag

Gets a tag from a specified repository in Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.
• RepoSlug: Repository slug/name.
• TagName: Name of the tag to retrieve.

Output:

• Tag (object): Dictionary of tag data retrieved from Bitbucket repository.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Current User

Gets the currently logged in user from Bitbucket using API token authentication.

Output:

• User (object): User data retrieved from Bitbucket.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Workspaces

Gets all workspaces for the current user from Bitbucket using API token authentication.

Output:

• Workspaces (object-array): Workspace data retrieved from Bitbucket.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Workspace Members

Gets all members of the requested workspace from Bitbucket using API token authentication.

Input Parameters:

• Workspace: Bitbucket workspace name.

Options:

• Query: Query parameters for filtering by email address.

Output:

• Members (object-array): Member data retrieved from Bitbucket.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Workspace

Gets a detail of a specific workspace from Bitbucket using API token authentication.

Input Parameters:

• WorkspaceSlug: Workspace slug/name.

Output:

• Workspace (object): Workspace data retrieved from Bitbucket.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new repository in your Bitbucket account.

The workflow will consist of a Start node, a Bitbucket node configured to "Create a Repository", and an Answer node to display the result.

1. Add the Bitbucket Node

• On the workflow canvas, click the "+" button to add a new node.
• Select the "Tools" tab in the pop-up panel.
• Find and select "Bitbucket" from the list of tools.
• In the list of supported operations for Bitbucket, click on "Create a Repository" to add the node to the canvas.

2. Configure the Node

• Click on the newly added "Create a Repository" node to open its configuration panel on the right.
• Credentials: In the credentials field, click the dropdown menu and select your pre-configured Bitbucket credential.
• Parameters: Fill in the required input parameters for the action.
  • Workspace: Enter the name or slug of your Bitbucket workspace. This is typically your username or your team's name. For example, my-team-workspace.
  • RepoSlug: Provide a URL-friendly name for your new repository. This slug should only contain lowercase letters, numbers, hyphens, and underscores. For example, new-automation-project.
  • IsPrivate (Optional): Toggle this switch to true if you want the repository to be private, or false for a public repository.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
• Click the "Run Test" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the logs icon in the top-right corner to view the detailed input and output of the node, confirming that the repository was created.

After completing these steps, your workflow is fully configured. When run, it will create a new repository in your specified Bitbucket workspace.

6. FAQs

Q: I'm getting a 401 Unauthorized or 403 Forbidden error. What should I do?

A: This usually indicates an issue with your credentials or permissions. Please check the following:

• Correct Credentials: Ensure you have selected the correct Bitbucket credential in the node configuration.
• App Password Scopes: Go to your Bitbucket account settings and verify that the App Password you are using has the necessary permissions (scopes) for the operation you are trying to perform. For example, to create a repository, you need repository:write and repository:admin permissions.

Q: How do I find my Workspace slug?

A: Your workspace slug is part of the URL when you are browsing Bitbucket. For example, in the URL https://bitbucket.org/my-team-workspace/, the workspace slug is my-team-workspace.

Q: What is the difference between ProjectKey and RepoSlug?

A: A RepoSlug is the unique, URL-friendly identifier for a specific repository. A ProjectKey is an identifier for a project, which is a container used to organize multiple related repositories within a workspace. A repository can optionally belong to a project.

7. Official Documentation

For more in-depth information about the Bitbucket API and its capabilities, please refer to the Bitbucket Official API Documentation.