Add Bitbucket Integration Documentation and Update Related Files

fine-agent · fine-agent · commit 17ee2641d217 · 2024-12-08T11:47:07.000Z
- Created a new documentation file for Bitbucket integration, mirroring the structure of the existing GitLab integration documentation. This includes sections on prerequisites, setting up a Bitbucket pipeline, creating a CM configuration file, and installing the gitStream service. Notably, highlighted that the `add-label` action is not supported in Bitbucket.
- Updated the main documentation index to include a link to the new Bitbucket integration documentation for easy access.
- Enhanced the FAQ section to reflect Bitbucket support, specifically updating the 'What repos are supported?' section to mention Bitbucket alongside GitHub and GitLab, with the exception of the `add-label` action.
- Revised the 'How gitStream Works' documentation to include Bitbucket as a supported provider, ensuring all references to GitLab and GitHub now also mention Bitbucket.
- Updated the README file to indicate Bitbucket support, ensuring the features and installation sections reflect Bitbucket as a supported provider, similar to GitHub and GitLab.
- Added a default `.bitbucket-pipelines.yml` file as a template for users to set up their Bitbucket pipelines with gitStream, tailored similarly to the GitLab CI/CD setup.
- Created a default `cm` file for Bitbucket, providing users with a starting point for their Continuous Merge configurations, excluding any label-related actions.
diff --git a/README.md b/README.md
@@ -61,7 +61,7 @@ Our research shows that code reviews are [the most consistent bottleneck in the
 
 ## 🚀 Get Started
 
-gitStream is a GitHub / GitLab app that processes automations defined in Continuous Merge (CM) automation files contained in your git repos. You can test gitStream automations on your own PRs via the [gitStream playground](https://app.gitstream.cm/playground).
+gitStream is a GitHub / GitLab / Bitbucket app that processes automations defined in Continuous Merge (CM) automation files contained in your git repos. You can test gitStream automations on your own PRs via the [gitStream playground](https://app.gitstream.cm/playground).
 
 If you're ready to install gitStream, or want to explore its automation capabilities, [head over to the docs](https://docs.gitstream.cm). You can have your first automation up and running in as little as 2 minutes.
 
@@ -92,4 +92,4 @@ gitStream is a free product from the team at [LinearB](https://linearb.io/?utm_s
     <img alt="Novu Logo" src="https://raw.githubusercontent.com/linear-b/gitstream/a5d4aca7b923e5cd70c813df06dc70de97382d8c/docs/downloads/images/LinearB-logo-dark.png" width="280"/>
   </picture>
   </a>
-</div>
+</div>
diff --git a/docs/bitbucket-installation.md b/docs/bitbucket-installation.md
@@ -0,0 +1,74 @@
+---
+title: How to Setup gitStream with Bitbucket
+description: Install gitStream to your Bitbucket workspace.
+---
+# How to Setup gitStream with Bitbucket
+
+!!! info "Prerequisites"
+
+    1. Bitbucket Cloud account
+    2. Bitbucket Pipelines enabled
+    3. <a href="https://app.linearb.io/login" target="_blank">Login</a>, or <a href="https://app.linearb.io/sign-up" target="_blank">create a free account</a> on the LinearB app, and follow the steps to connect gitStream using a Bitbucket integration.
+
+Bitbucket Installation Overview
+
+1. Designate a gitStream user account.
+2. Create a CM configuration file.
+3. Create a Bitbucket pipeline.
+4. Install the gitStream service.
+
+## Designate a gitStream User Account
+
+gitStream automation rules are executed on behalf of the user account configured when you install the gitStream service. This account must have the necessary permissions to the relevant repositories.
+
+We recommend creating a dedicated service account to control access to individual repositories easily. You can also use your professional or personal Bitbucket account for this, which would result in all automations being executed under that account.
+
+!!! tip "Use this account when you integrate gitStream"
+    Make sure to use this account when authorizing Bitbucket in LinearB.
+
+## Create a CM Configuration File
+
+Create a `gitstream.cm` rules file in the root directory of your repository's default branch (usually `master` or `main`). This file will contain a YAML configuration that determines the workflows that run on your repositories. You can name the CM file anything you want as long as it ends in `.cm`.
+
+!!! info "Configuration files go in the repo's root directory."
+    Your `.cm` files should be placed in the repository's root directory.
+
+!!! example "Example Configuration"
+    ```yaml
+    --8<-- "docs/downloads/gitstream.cm"
+    ```
+
+## Create a Bitbucket Pipeline
+
+Once your gitStream configuration file is set up, you need a Bitbucket Pipelines configuration file to trigger gitStream automations. Create a `.bitbucket-pipelines.yml` file in your repository's default branch (usually `master` or `main`) and add the following configuration:
+
+```yaml
+--8<-- "docs/downloads/bitbucket-pipelines.yml"
+```
+
+!!! warning "Note"
+    The `add-label` action is not supported in Bitbucket as Bitbucket does not have a native labeling feature.
+
+## Install the gitStream Service
+
+To complete the setup, install the gitStream service in your Bitbucket workspace. Follow the instructions provided in the LinearB app to connect your Bitbucket account and repositories to gitStream.
+
+## Next Step
+If you successfully complete these instructions, gitStream will now automate your code review workflows in Bitbucket.
+
+!!! tip "How gitStream Works"
+    Read our guide, [How gitStream Works](/how-it-works/), for a deeper understanding of gitStream's capabilities and how to leverage them fully.
+
+## Additional Resources
+
+### Required Bitbucket Permissions
+
+The required permissions are:
+
+| Permissions       | Reason                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------- |
+| Read/Write API    | To get notified on PR changes and allow gitStream to approve PRs once all conditions are met |
+| Read repository   | To read and check rules over the code changes on monitored repositories                      |
+| Read user profile | Used to identify users                                                                       |
+
+</markdown>
diff --git a/docs/faq.md b/docs/faq.md
@@ -23,7 +23,7 @@ In order to support automations that either Approve or Merge PRs, GitHub API req
 
 ## What repos are supported?
 
-Any repo in GitHub is supported. More Git providers are planned soon.
+gitStream supports repositories in GitHub, GitLab, and Bitbucket. Note that the `add-label` action is not supported in Bitbucket as it does not have a native labeling feature.
 
 ## Can I use gitStream with Merge Queues?
 
@@ -54,4 +54,4 @@ Get a plug-in that enable modelines, popular ones are:
 
 Go to our issues page and check if there are any similar issues already reported. If not, create a new issue with all the details so we can take a look.
 
-Found a bug? Create a new item in the [project's issues](https://github.com/linear-b/gitstream/issues)
+Found a bug? Create a new item in the [project's issues](https://github.com/linear-b/gitstream/issues)
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
@@ -3,7 +3,7 @@ title: How gitStream Works
 description: Learn how gitStream automates code review workflows.
 ---
 # How gitStream Works
-You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab organization. These files end with a `.cm`  extension, and they outline automations that will run for your repo's pull requests. 
+You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab/Bitbucket organization. These files end with a `.cm`  extension, and they outline automations that will run for your repo's pull requests. 
 ## Syntax Overview
 CM files contain a combination of YAML and Jinja2 to build rules that follow an "if this, then that" approach to triggering and executing automations. This, combined with templating and gitStream-specific functions gives you a highly-flexible framework for building custom CM automations.
 
@@ -143,9 +143,9 @@ Once you have gitStream installed and have run some automations, you can view de
 
 Once gitStream is installed and configured, there are several services that will interact with your repository whenever a PR is created or changed:
 
-* The **git service provider API** (e.g. GitHub, Gitlab)
+* The **git service provider API** (e.g. GitHub, GitLab, Bitbucket)
 * The **gitStream service** that was installed from the git service provider marketplace.
-* A **gitStream CI/CD script** that is configured for the git service provider (e.g. GitHub Actions, GitLab CI/CD).
+* A **gitStream CI/CD script** that is configured for the git service provider (e.g. GitHub Actions, GitLab CI/CD, Bitbucket Pipelines).
 * A **gitStream agent** the CI/CD script triggers to execute your automation.
 
 Whenever a new PR is opened or an existing PR is changed (see also [Execution Model](https://docs.gitstream.cm/execution-model/)), the following process occurs:
@@ -192,4 +192,4 @@ You can add support for `.cm` in your code editor, see [FAQ](https://docs.gitstr
 
 ## Is something missing?
 
-If you find an issue with these docs or with gitStream itself, please search the  [gitStream issues page](https://github.com/linear-b/gitstream/issues) and create an issue if one doesn't already exist for your problem.
+If you find an issue with these docs or with gitStream itself, please search the  [gitStream issues page](https://github.com/linear-b/gitstream/issues) and create an issue if one doesn't already exist for your problem.
diff --git a/docs/index.md b/docs/index.md
@@ -68,9 +68,12 @@ gitStream is a workflow automation tool that enables you to use YAML configurati
 	
 	That's it! Now sit back and watch gitStream run automation rules on your next PR.
 
-=== ":fontawesome-brands-bitbucket: BitBucket"
+=== ":fontawesome-brands-bitbucket: Bitbucket"
 
-	Coming soon
+	1. <a href="https://app.linearb.io/login" target="_blank">Login</a>, or <a href="https://app.linearb.io/sign-up" target="_blank">create a free account</a> on the LinearB app.
+	2. Connect gitStream to your Bitbucket repos by following the steps described in the [Bitbucket installation guide](bitbucket-installation.md).
+	
+	That's it! Now sit back and watch gitStream run automation rules on your next PR.
 
 
 ## Get Involved
diff --git a/templates/bitbucket-cm.yml b/templates/bitbucket-cm.yml
@@ -0,0 +1,37 @@
+# -*- mode: yaml -*-
+manifest:
+  version: 1.0
+automations:
+  auto_approve_safe_changes:
+    if:
+      - {{ files | allDocs | some }}
+      - {{ files | allTests | some }}
+    run:
+      - action: approve@v1
+        args:
+          message: "Automatically approved safe changes."
+
+  request_additional_review_for_large_prs:
+    if:
+      - {{ files | length > 10 }}
+    run:
+      - action: set-required-approvals@v1
+        args:
+          approvals: 2
+
+  notify_code_experts:
+    if:
+      - {{ files | extensions | includes('js') }}
+    run:
+      - action: add-comment@v1
+        args:
+          comment: "This PR contains JavaScript files. Please ensure a JavaScript expert reviews this PR."
+
+  enforce_changelog_update:
+    if:
+      - {{ files | match(regex=r'/src/') | some }}
+      - {{ not (files | includes('CHANGELOG.md')) }}
+    run:
+      - action: request-changes@v1
+        args:
+          message: "Please update the CHANGELOG.md file for changes in the src directory."
diff --git a/templates/bitbucket-pipelines.yml b/templates/bitbucket-pipelines.yml
@@ -0,0 +1,11 @@
+image: atlassian/default-image:2
+
+pipelines:
+  default:
+    - step:
+        name: Run gitStream
+        script:
+          - pipe: docker://linear-b/gitstream-bitbucket-pipe:latest
+            variables:
+              GITSTREAM_CONFIG_PATH: '.cm/gitstream.cm'
+              GITSTREAM_API_TOKEN: $GITSTREAM_API_TOKEN
