Add detailed IP allowlisting explanation for all Git providers

docs/bitbucket-installation.md

@@ -19,6 +19,26 @@ description: Install gitStream to your Bitbucket workspace.
         - 13.56.203.235
         - 54.151.81.98
 
+??? Info "Understanding IP Allowlisting for gitStream"
+    When setting up IP allowlists in Bitbucket, you're specifying which source IP addresses are permitted to interact with your repositories and APIs. This affects both gitStream and your CI/CD runners.
+
+    There are two primary cases where this matters for gitStream:
+
+    1. **Webhook Event Handling by gitStream**
+       When Bitbucket triggers a webhook event (e.g., a pull request opened), gitStream may need to make follow-up API calls to Bitbucket. This can include fetching additional metadata, posting comments to the PR, or performing other actions. These calls are made from the LinearB/gitStream service, which uses a fixed set of IP addresses. These IPs must be added to your Bitbucket allowlist to ensure proper operation.
+
+    2. **Outbound Requests from Your CI Runner**
+       When your pipeline runs gitStream, that runner might also make outbound calls to Bitbucket—for example, to clone a repository or retrieve commit history. These requests will originate from the runner's IP address.
+
+    If you encounter errors due to blocked IPs during your CI runs, it's likely that the runner is using an IP that is not part of the configured allowlist.
+
+    **Recommended Solution**
+    To ensure reliability:
+    - Add LinearB/gitStream service IPs to your Bitbucket allowlist (listed above).
+    - Use self-hosted runners or runners with static IPs so you can manage and allowlist their addresses explicitly.
+
+    This combination ensures that both gitStream's internal operations and your CI runners' interactions with Bitbucket function without network restrictions.
+
 Bitbucket Installation Overview
 
 1. Designate a gitStream user account.

docs/github-installation.md

@@ -6,10 +6,30 @@ description: Install gitStream to your GitHub organization.
 
 !!! Info "Prerequisites"
     Allowed network connection between the runners and the following IPs:
-    
+
     - 13.56.203.235
     - 54.151.81.98
 
+??? Info "Understanding IP Allowlisting for gitStream"
+    When setting up IP allowlists in GitHub, you're specifying which source IP addresses are permitted to interact with your repositories and APIs. This affects both gitStream and your CI/CD runners.
+
+    There are two primary cases where this matters for gitStream:
+
+    1. **Webhook Event Handling by gitStream**
+       When GitHub triggers a webhook event (e.g., a pull request opened), gitStream may need to make follow-up API calls to GitHub. This can include fetching additional metadata, posting comments to the PR, or performing other actions. These calls are made from the LinearB/gitStream service, which uses a fixed set of IP addresses. These IPs must be added to your GitHub allowlist to ensure proper operation.
+
+    2. **Outbound Requests from Your CI Runner**
+       When your pipeline runs gitStream (e.g., via a GitHub Action), that runner might also make outbound calls to GitHub—for example, to clone a repository or retrieve commit history. These requests will originate from the runner's IP address.
+
+    If you encounter errors due to blocked IPs during your CI runs, it's likely that the runner is using an IP that is not part of the configured allowlist. This is a common issue with GitHub-hosted runners, as their IPs can be dynamic and change frequently.
+
+    **Recommended Solution**
+    To ensure reliability:
+    - Add LinearB/gitStream service IPs to your GitHub allowlist (listed above).
+    - Use self-hosted runners or runners with static IPs so you can manage and allowlist their addresses explicitly.
+
+    This combination ensures that both gitStream's internal operations and your CI runners' interactions with GitHub function without network restrictions.
+
 !!! Warning "Install gitStream"
 
     Before you can complete the gitStream setup process, you need to install the gitStream app to your [GitHub organization](https://github.com/apps/gitstream-cm/installations/new){ .md-button }.

docs/gitlab-installation.md

@@ -13,16 +13,36 @@ description: Install gitStream to your GitLab organization.
         - 13.56.203.235
         - 54.151.81.98
 
+??? Info "Understanding IP Allowlisting for gitStream"
+    When setting up IP allowlists in GitLab, you're specifying which source IP addresses are permitted to interact with your repositories and APIs. This affects both gitStream and your CI/CD runners.
+
+    There are two primary cases where this matters for gitStream:
+
+    1. **Webhook Event Handling by gitStream**
+       When GitLab triggers a webhook event (e.g., a merge request opened), gitStream may need to make follow-up API calls to GitLab. This can include fetching additional metadata, posting comments to the MR, or performing other actions. These calls are made from the LinearB/gitStream service, which uses a fixed set of IP addresses. These IPs must be added to your GitLab allowlist to ensure proper operation.
+
+    2. **Outbound Requests from Your CI Runner**
+       When your pipeline runs gitStream, that runner might also make outbound calls to GitLab—for example, to clone a repository or retrieve commit history. These requests will originate from the runner's IP address.
+
+    If you encounter errors due to blocked IPs during your CI runs, it's likely that the runner is using an IP that is not part of the configured allowlist.
+
+    **Recommended Solution**
+    To ensure reliability:
+    - Add LinearB/gitStream service IPs to your GitLab allowlist (listed above).
+    - Use self-hosted runners or runners with static IPs so you can manage and allowlist their addresses explicitly.
+
+    This combination ensures that both gitStream's internal operations and your CI runners' interactions with GitLab function without network restrictions.
+
 GitLab Installation Overview
 
 1. Designate a gitStream user account.
 1. Create a `cm` repo and `.cm` configuration file.
 1. Create a GitLab pipeline.
-1. Connect gitStream in LinearB. 
+1. Connect gitStream in LinearB.
 
 ## 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 `maintainer` or `owner` role to the relevant repos. 
+gitStream automation rules are executed on behalf of the user account configured when you install the gitStream service. This account must have the `maintainer` or `owner` role to the relevant repos.
 
 We recommend creating a [dedicated service account](https://docs.gitlab.com/ee/user/profile/service_accounts.html){:target="_blank"} to control access to individual repos easily. You can also use your professional or personal GitLab account for this, which would result in all automations being executed under that account, which might also affect LinearB's metrics.
 
@@ -50,7 +70,7 @@ Once your gitStream configuration file is set up, you need a GitLab CI configura
 === "GitLab-Hosted runners"
 
     **Gitlab-Hosted Runners**
-    
+
     Use the following `.gitlab-ci.yml`
 
 	``` yaml+jinja
@@ -68,14 +88,14 @@ Once your gitStream configuration file is set up, you need a GitLab CI configura
     ``` yaml+jinja
     --8<-- "docs/downloads/gitlab-shell-ci.yml"
     ```
-    
+
 === "Self-Managed Runners - Kubernetes"
     **Self-Managed Runners**
 
 	First, [register the runner](https://docs.gitlab.com/runner/register/){:target="_blank"} with a tag, and use the named tag in the `.gitlab-ci.yml` file
 
 	**Kubernetes executors**
-	
+
     1. Ensure your runner configuration (`config.toml` for example) has the followig:
 	``` yaml
 	[runners.kubernetes]
@@ -93,7 +113,7 @@ Once your gitStream configuration file is set up, you need a GitLab CI configura
     - ...
     - docker pull YOUR-REGISTRY-URL/gitstream/rules-engine:latest
 	```
-	The docker image can be pulled to your private repository from [DockerHub](https://hub.docker.com/r/gitstream/rules-engine){:target=_blank}.  
+	The docker image can be pulled to your private repository from [DockerHub](https://hub.docker.com/r/gitstream/rules-engine){:target=_blank}.
 
 ## Connect gitStream in LinearB
 
@@ -117,5 +137,3 @@ The required permissions are:
 | Read/Write API    | To get notified on MR changes and allow gitStream to approve MRs 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                                                                       |
-
-