From 1009a47165681f2993683b6f138a22060f2e7556 Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Thu, 22 May 2025 15:05:39 +0300 Subject: [PATCH 1/3] Add detailed IP allowlisting explanation for all Git providers --- docs/bitbucket-installation.md | 18 ++++++++++++++++++ docs/github-installation.md | 18 ++++++++++++++++++ docs/gitlab-installation.md | 18 ++++++++++++++++++ 3 files changed, 54 insertions(+) diff --git a/docs/bitbucket-installation.md b/docs/bitbucket-installation.md index 0c70445dc..d1333f0d6 100644 --- a/docs/bitbucket-installation.md +++ b/docs/bitbucket-installation.md @@ -19,6 +19,24 @@ 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. diff --git a/docs/github-installation.md b/docs/github-installation.md index 04ebcfcb9..3788cfbba 100644 --- a/docs/github-installation.md +++ b/docs/github-installation.md @@ -10,6 +10,24 @@ description: Install gitStream to your GitHub organization. - 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 }. diff --git a/docs/gitlab-installation.md b/docs/gitlab-installation.md index 841c024a7..31702d679 100644 --- a/docs/gitlab-installation.md +++ b/docs/gitlab-installation.md @@ -13,6 +13,24 @@ 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. From 1200fedc70160fccdc78106689194f96ffae9b6e Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Thu, 22 May 2025 15:08:05 +0300 Subject: [PATCH 2/3] collapsable --- docs/bitbucket-installation.md | 2 +- docs/github-installation.md | 2 +- docs/gitlab-installation.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/bitbucket-installation.md b/docs/bitbucket-installation.md index d1333f0d6..7fe4d8668 100644 --- a/docs/bitbucket-installation.md +++ b/docs/bitbucket-installation.md @@ -19,7 +19,7 @@ description: Install gitStream to your Bitbucket workspace. - 13.56.203.235 - 54.151.81.98 -!!! Info "Understanding IP Allowlisting for gitStream" +??? 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: diff --git a/docs/github-installation.md b/docs/github-installation.md index 3788cfbba..4140b247a 100644 --- a/docs/github-installation.md +++ b/docs/github-installation.md @@ -10,7 +10,7 @@ description: Install gitStream to your GitHub organization. - 13.56.203.235 - 54.151.81.98 -!!! Info "Understanding IP Allowlisting for gitStream" +??? 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: diff --git a/docs/gitlab-installation.md b/docs/gitlab-installation.md index 31702d679..c4f29a795 100644 --- a/docs/gitlab-installation.md +++ b/docs/gitlab-installation.md @@ -13,7 +13,7 @@ description: Install gitStream to your GitLab organization. - 13.56.203.235 - 54.151.81.98 -!!! Info "Understanding IP Allowlisting for gitStream" +??? 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: From 6b39d07e75ad50aff6abfaf4415aec14cea4df17 Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Thu, 22 May 2025 15:10:00 +0300 Subject: [PATCH 3/3] fixed bullet list --- docs/bitbucket-installation.md | 2 ++ docs/github-installation.md | 4 +++- docs/gitlab-installation.md | 16 ++++++++-------- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/bitbucket-installation.md b/docs/bitbucket-installation.md index 7fe4d8668..f7290e450 100644 --- a/docs/bitbucket-installation.md +++ b/docs/bitbucket-installation.md @@ -23,8 +23,10 @@ description: Install gitStream to your Bitbucket workspace. 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. diff --git a/docs/github-installation.md b/docs/github-installation.md index 4140b247a..6744c8025 100644 --- a/docs/github-installation.md +++ b/docs/github-installation.md @@ -6,7 +6,7 @@ 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 @@ -14,8 +14,10 @@ description: Install gitStream to your GitHub organization. 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. diff --git a/docs/gitlab-installation.md b/docs/gitlab-installation.md index c4f29a795..93711bd61 100644 --- a/docs/gitlab-installation.md +++ b/docs/gitlab-installation.md @@ -17,8 +17,10 @@ description: Install gitStream to your GitLab organization. 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. @@ -36,11 +38,11 @@ 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. @@ -68,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 @@ -86,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] @@ -111,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 @@ -135,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 | - -