- 13.56.203.235
- 54.151.81.98

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.

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 }.

You must implement two main components for gitStream to function for a single GitHub repo. The first is a configuration file that defines the workflow automations to execute for the repo. The second is a GitHub actions configuration file that triggers gitStream when PRs are created or updated.
!!! example "Required Configurations"
    **gitStream**

    Create a `.cm/gitstream.cm` rules file in your repository's default branch (usually `master` or `main`). This file will contain a YAML configuration that determines the workflows that run on the repo, and you can name it anything you want as long as it ends in `.cm`

    Here is an example of a gitStream configuration file you can use to setup some basic workflow automations.

    ```yaml+jinja
    --8<-- "docs/downloads/gitstream.cm"
    ```

    **GitHub Actions**

    Once your gitStream configuration file is setup, you need a GitHub Actions configuration file to trigger gitStream automations. Create a `.github/workflows/gitstream.yml` file in your repository's default branch (usually `master` or `main`) and add the following configuration:

    ```yaml+jinja
    --8<-- "docs/downloads/gitstream.yml"
    ```

    <div class="result" markdown>
      <span>
      [:octicons-download-24: Download gitstream.yml (regular version)](/downloads/gitstream.yml){ .md-button }
      </span>
    </div>

    !!! tip "Large Repository Support (Lite Version)"
        If you're working with a large repository (typically monorepos) and experience timeout issues during GitHub Actions execution, you can use the lite version of gitStream that performs a shallow clone to reduce execution time:

        ```yaml
        jobs:
          gitStream:
            timeout-minutes: 15
            runs-on: ubuntu-latest
            name: gitStream workflow automation
            steps:
              - name: Evaluate Rules
                uses: linear-b/gitstream-github-action@v2-lite
                id: rules-engine
        ```

        **Important:** The lite version has limitations - automations that rely on Git history (such as code-experts) may not work properly due to the shallow clone.

    <div class="result" markdown>
      <span>
      [:octicons-download-24: Download gitstream.yml (lite version)](/downloads/gitstream-lite.yml){ .md-button }
      </span>
    </div>
    
    !!! Success
        When finished, you should have the following file structure in your repo.

        ```
        .
        ├─ .cm/
        │  └─ gitstream.cm
        ├─ .github/
        │  └─ workflows/
        │     └─ gitstream.yml
        ```

Organization rules are ideal when you want to enforce consistent rules across every repo in your organization. You can define them by creating a special repository named `cm` in your GitHub organization where you can add automation files that will apply to **all** repositories within that organization.

!!! Tip "Prerequisite: Create a cm repo and enable gitStream."
    Organization-wide automations need to be defined in a repo named "cm" inside your GitHub organization. Before continuing, you must create this repo and <a href="https://github.com/apps/gitstream-cm/installations/new" target="_blank">enable the gitStream app for it</a>.

!!! example "Required Configurations"
    **gitStream**

    Create a `gitstream.cm` rules file in the root directory of your cm repository's default branch (usually `master` or `main`). This file will contain a YAML configuration that determines the workflows that run on your organization's repos. You can name it anything you want as long as it ends in `.cm`

    !!! info "Configuration files go in the repo's root directory."
        Unlike the set up instructions for a single repo, your `.cm` files should be placed in the repository's root directory.
    ```yaml+jinja
    --8<-- "docs/downloads/gitstream.cm"
    ```
    **GitHub Actions**

    Once your gitStream configuration file is set up, you will need to create a GitHub Actions configuration file to trigger gitStream automations. Create a `.github/workflows/gitstream.yml` file in your `cm` repository's default branch (usually `master` or `main`) and add the following configuration:

    ```yaml+jinja
    --8<-- "docs/downloads/gitstream.yml"
    ```

    <div class="result" markdown>
      <span>
      [:octicons-download-24: Download gitstream.yml (regular version)](/downloads/gitstream.yml){ .md-button }
      </span>
    </div>

    !!! tip "Large Repository Support (Lite Version)"
        If you're working with large repositories in your organization (typically monorepos) and experience timeout issues during GitHub Actions execution, you can use the lite version of gitStream that performs a shallow clone to reduce execution time:

        ```yaml
        jobs:
          gitStream:
            timeout-minutes: 15
            runs-on: ubuntu-latest
            name: gitStream workflow automation
            steps:
              - name: Evaluate Rules
                uses: linear-b/gitstream-github-action@v2-lite
                id: rules-engine
        ```

        **Important:** The lite version has limitations - automations that rely on Git history (such as code-experts) may not work properly due to the shallow clone. See the [troubleshooting section](/troubleshooting/#github-timeout-issues-with-large-repositories) for more details.

    <div class="result" markdown>
      <span>
      [:octicons-download-24: Download gitstream.yml (lite version)](/downloads/gitstream-lite.yml){ .md-button }
      </span>
    </div>
    
    !!! Success
        Once finished, **all** PRs to your organization's repositories will be processed by the GitHub Action in this repo, and your `cm` repo should have a file directory that looks like this.

        ```
        .
        ├─ gitstream.cm
        ├─ .github/
        │  └─ workflows/
        │     └─ gitstream.yml
        ```