GitHub Server Installation (Custom App) – LinearB Support

Use this guide to set up a custom GitHub App on your self-hosted GitHub Server instance and connect it to gitStream and LinearB.

Overview

For self-hosted GitHub Server (GitHub Enterprise Server), gitStream connects via a custom GitHub App. The app:

Authenticates via OAuth3.
Lets users select which repositories gitStream can access.
Receives webhooks and triggers gitStream automations on pull requests.

At a high level, you will:

Start setup in LinearB and copy the Webhook URL and secret.
Create and configure a GitHub App on your GitHub Server.
Generate an App ID and private key (.pem file).
Paste those values back into LinearB.
Install the GitHub App on your org(s) and repositories.
Add gitStream config + workflow files to your repos.

Before you begin

Prerequisites

GitHub Server account with access to:
- Organization settings.
- Developer settings → GitHub Apps.
LinearB account with Admin access.

Network requirements

Your GitHub Server must be able to reach gitStream / LinearB at specific IPs. Allow outbound connections from GitHub Server to the following IP addresses (as provided by gitStream docs):

13.56.203.235
54.151.81.98

If you use additional firewall, proxy, or VPN layers, make sure these IPs are allowlisted.

Expected time

App creation and configuration: ~15–25 minutes.
Repo setup (config + workflow): ~5–10 minutes per repo or per org-wide config.

Step 1. Start setup in LinearB

Get the Webhook URL and secret from LinearB

Log in to the LinearB app.
Go to Settings → Git.
Locate your GitHub Server integration.
Click Connect gitStream (or equivalent gitStream setup button).
Copy the Webhook URL and Webhook secret provided on this screen. Leave this page open; you’ll paste these values into the GitHub App configuration.

Step 2. Create a new GitHub App

Create the app on your GitHub Server instance

Log in to your self-hosted GitHub Server.
Navigate to the organization account that will own the app (recommended):
https://<GITHUB_SERVER_URL>/<org-name>
Go to Settings → Developer settings → GitHub Apps.
Click New GitHub App.
Alternatively, go directly to:
https://<GITHUB_SERVER_URL>/settings/apps

Step 3. Configure URLs & general settings

General & URL configuration

Fill in the app details according to your environment and gitStream endpoint.

GitHub App name: Must contain gitstream in lowercase. For example: gitstream app.
Homepage URL: You can use https://gitstream.cm or your internal gitStream landing page.
Callback URL / App URLs: Use the URLs provided in the gitStream / LinearB docs for your self-hosted gitStream deployment (for example, https://gitstream.<your-domain>.com/...). Replace <your-domain> with your real domain.
Webhook URL: Paste the Webhook URL from the LinearB gitStream setup page.
Webhook secret: Paste the Webhook secret from the LinearB gitStream setup page.

Important notes:

Do not forget the trailing slash on URLs if required by the gitStream docs.
Disable the “Expire user authorization tokens” checkbox.
Double-check all URLs for typos before continuing.

Step 4. Set GitHub App permissions

Required permissions

Configure the GitHub App permissions to allow gitStream to read PRs, manage checks, and (optionally) approve PRs when rules are satisfied.

Typical permissions include:

Repository contents: Read & write (to manage gitStream workflow files where required).
Code: Write (to allow gitStream to approve PRs when all conditions are met).
Administration / Metadata / Issues: Read (to get team membership and branch protection details, where needed).
Actions, Checks, Pull requests, Workflows: Read & write (to trigger workflows, manage checks, and update PR state).
User email: Read (to help identify users).

Path restrictions (recommended):

For content path restrictions, add these paths to limit where the app can write:

.cm/gitstream.cm
.github/workflows/gitstream.yml

This ensures the app only writes to the gitStream configuration and workflow files.

Step 5. Configure webhook events & install scope

Webhook events & app installation scope

Webhook events:

Subscribe to events so gitStream is notified when relevant Git activity occurs. At minimum, enable events for:

Pull requests (opened, synchronized, closed, reopened).
Push events.
Other events recommended in the gitStream documentation (for example, check runs, issue comments, etc.).

Installation scope:

Under “Where can this GitHub App be installed?”, choose:

Any account – recommended, so other orgs on your GitHub Server can also install the app if needed.

Step 6. Generate and save the private key

Generate the .pem private key

After saving your app settings, scroll down to the Private keys section.
Click Generate a private key.
A .pem file will be downloaded. Store it securely.
You will upload this file (or paste its contents) into the LinearB setup screen.

Step 7. Get the App ID

Locate the App ID for your GitHub App

On your GitHub App’s settings page, locate the App ID.
Copy the App ID value and keep it with your .pem private key.

Step 8. Complete setup in LinearB

Connect the custom app to LinearB

Return to the LinearB gitStream setup page you left open in Step 1.
Enter:
- App ID (from the GitHub App settings).
- Private key (upload the .pem file or paste its contents, depending on the UI).
Click Save or Connect to complete the connection.

Step 9. Install the GitHub App on organizations & repositories

Install the app where you want gitStream to run

In GitHub Server, go to your organization settings and open GitHub Apps / Third-party access.
Select the gitStream app you just created.
Install the app:
- Either on a single organization, or
- On multiple orgs (multi-org support) if your company uses several GitHub Server orgs.
Choose which repositories the app can access:
- All repositories – recommended if you want coverage now and for future repos; or
- Only select repositories – if you’re running a pilot or want tighter control.

Step 10. Finish setting up gitStream as applicable

gitStream Setup per GitHub Repo

Setup gitStream on a repo-level

You must implement two main components for gitStream to function for a single GitHub repo:

A gitStream configuration file that defines the workflow automations to execute for the repo.
A GitHub Actions configuration file that triggers gitStream when PRs are created or updated.

Required Configurations – gitStream

Create a .cm/gitstream.cm rules file in your repository's default branch (usually master or main). This file contains a YAML configuration that determines the workflows that run on the repo. 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 set up some basic workflow automations:

# -*- mode: yaml -*-
manifest:
  version: 1.0

automations:
  linearb_ai_codereview:
    # Ai Code Review - Triggers only when PR is ready for review, see docs https://docs.gitstream.cm/execution-model/#action-level-execution-control
    on: [pr_created, pr_ready_for_review, merge]
    if:
      - {{ not is.bot }}
    run:
      - action: code-review@v1
        args:
          guidelines: |
            - Highlight **critical issues** only (correctness/logic, performance, security, maintainability blockers).
            - Skip nitpicks; ignore null-reference risks that are known to be validated earlier in this code path.
            - Keep suggestions short and actionable.

  pr_policy_low_noise:
    on: [pr_created, commit]
    if:
      - {{ not pr.draft }}
      - {{ not is.bot }}
    run:
      # AI description (updates PR body; not a comment)
      - action: describe-changes@v1
        args:
          concat_mode: append

      # Quiet labels
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ colors.red if (calc.etr >= 20) else (colors.yellow if (calc.etr >= 5) else colors.green) }}

      - action: add-label@v1
        when :  {{ pr.unresolved_threads }}
        args:
          label: "{{ pr.unresolved_threads | default(value=0) }} unresolved thread(s)"
          color: {{ colors.yellow }}

      - action: add-label@v1
        when: {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
        args:
          label: "missing-jira"
          color: {{ colors.red }}
          # further automations available with Jira webhook

      # Assign reviewers silently
      - action: add-reviewers@v1
        args:
          reviewers: {{ who.experts }}

      # ONE consolidated, updatable comment
      - action: add-comment@v1
        args:
          comment: |
            ## gitStream Summary — Low Noise (Staff Engineer focus)

            **AI PR Description:** Updated in the PR body above.
            **ETR:** {{ calc.etr }} min review
            **Unresolved threads:** {{ pr.unresolved_threads | default(value=0) }}

            ### Suggested Reviewers (auto-assigned)
            {{ who.experts }}

            ### Jira Reference
            {{ '✅ Found in title/description.' if (has.jira_ticket_in_title or has.jira_ticket_in_desc) else '⚠️ Missing Jira ticket. Please add one (e.g., `ABC-123` or an `atlassian.net/browse/...` link).' }}

            > Labels/reviewers were applied quietly to keep this PR clean.

# ----------------- config -----------------
calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title       | includes(regex=r/\b[A-Za-z][A-Za-z0-9_]+-\d+\b/) }}
  jira_ticket_in_desc:  {{ pr.description | includes(regex=r/\b[A-Za-z][A-Za-z0-9_]+-\d+\b/) }}

who:
  experts: {{ repo | codeExperts(gt=10, top=5) }}

is:
  bot: {{ pr.author | match(list=['github-actions','_bot_','[bot]','dependabot','gitstream-cm','dayforce-global-sonar-integration','prvalidation','aida-bot']) | some }}

colors:
  red:    'b60205'
  yellow: 'fbca04'
  green:  '0e8a16'

GitHub Actions

Once your gitStream configuration file is set up, 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:

# Code generated by gitStream GitHub app - DO NOT EDIT

name: gitStream workflow automation
run-name: |
  /:\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}

on:
  workflow_dispatch:
    inputs:
      client_payload:
        description: The Client payload
        required: true
      full_repository:
        description: the repository name include the owner in `owner/repo_name` format
        required: true
      head_ref:
        description: the head sha
        required: true
      base_ref:
        description: the base ref
        required: true
      installation_id:
        description: the installation id
        required: false
      resolver_url:
        description: the resolver url to pass results to
        required: true
      resolver_token:
        description: Optional resolver token for resolver service
        required: false
        default: ''

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Adding PR Url
        run: |
          echo '[${{ fromJSON(fromJSON(inputs.client_payload)).repo }}#${{ fromJSON(fromJSON(inputs.client_payload)).prContext.number }}](${{ fromJSON(fromJSON(inputs.client_payload)).prContext.url }}) - `${{ fromJSON(fromJSON(inputs.client_payload)).branch }}` by ${{ fromJSON(fromJSON(inputs.client_payload)).prContext.author }}' >> $GITHUB_STEP_SUMMARY

      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine
        with:
          full_repository: ${{ github.event.inputs.full_repository }}
          head_ref: ${{ github.event.inputs.head_ref }}
          base_ref: ${{ github.event.inputs.base_ref }}
          client_payload: ${{ github.event.inputs.client_payload }}
          installation_id: ${{ github.event.inputs.installation_id }}
          resolver_url: ${{ github.event.inputs.resolver_url }}
          resolver_token: ${{ github.event.inputs.resolver_token }}

Success

When finished, you should have the following file structure in your repo:

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

GitHub Organization-wide gitStream Setup

Setup gitSteam at the org-level

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.

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 enable the gitStream app for it.

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

Configuration files go in the repo's root directory.
Unlike the setup instructions for a single repo, your .cm files should be placed in the repository's root directory.

# -*- mode: yaml -*-
manifest:
  version: 1.0

automations:
  linearb_ai_codereview:
    # Ai Code Review - Triggers only when PR is ready for review, see docs https://docs.gitstream.cm/execution-model/#action-level-execution-control
    on: [pr_created, pr_ready_for_review, merge]
    if:
      - {{ not is.bot }}
    run:
      - action: code-review@v1
        args:
          guidelines: |
            - Highlight **critical issues** only (correctness/logic, performance, security, maintainability blockers).
            - Skip nitpicks; ignore null-reference risks that are known to be validated earlier in this code path.
            - Keep suggestions short and actionable.

  pr_policy_low_noise:
    on: [pr_created, commit]
    if:
      - {{ not pr.draft }}
      - {{ not is.bot }}
    run:
      # AI description (updates PR body; not a comment)
      - action: describe-changes@v1
        args:
          concat_mode: append

      # Quiet labels
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ colors.red if (calc.etr >= 20) else (colors.yellow if (calc.etr >= 5) else colors.green) }}

      - action: add-label@v1
        when :  {{ pr.unresolved_threads }}
        args:
          label: "{{ pr.unresolved_threads | default(value=0) }} unresolved thread(s)"
          color: {{ colors.yellow }}

      - action: add-label@v1
        when: {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
        args:
          label: "missing-jira"
          color: {{ colors.red }}
          # further automations available with Jira webhook

      # Assign reviewers silently
      - action: add-reviewers@v1
        args:
          reviewers: {{ who.experts }}

      # ONE consolidated, updatable comment
      - action: add-comment@v1
        args:
          comment: |
            ## gitStream Summary — Low Noise (Staff Engineer focus)

            **AI PR Description:** Updated in the PR body above.
            **ETR:** {{ calc.etr }} min review
            **Unresolved threads:** {{ pr.unresolved_threads | default(value=0) }}

            ### Suggested Reviewers (auto-assigned)
            {{ who.experts }}

            ### Jira Reference
            {{ '✅ Found in title/description.' if (has.jira_ticket_in_title or has.jira_ticket_in_desc) else '⚠️ Missing Jira ticket. Please add one (e.g., `ABC-123` or an `atlassian.net/browse/...` link).' }}

            > Labels/reviewers were applied quietly to keep this PR clean.

# ----------------- config -----------------
calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title       | includes(regex=r/\b[A-Za-z][A-Za-z0-9_]+-\d+\b/) }}
  jira_ticket_in_desc:  {{ pr.description | includes(regex=r/\b[A-Za-z][A-Za-z0-9_]+-\d+\b/) }}

who:
  experts: {{ repo | codeExperts(gt=10, top=5) }}

is:
  bot: {{ pr.author | match(list=['github-actions','_bot_','[bot]','dependabot','gitstream-cm','dayforce-global-sonar-integration','prvalidation','aida-bot']) | some }}

colors:
  red:    'b60205'
  yellow: 'fbca04'
  green:  '0e8a16'

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:

# Code generated by gitStream GitHub app - DO NOT EDIT

name: gitStream workflow automation
run-name: |
  /:\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}

on:
  workflow_dispatch:
    inputs:
      client_payload:
        description: The Client payload
        required: true
      full_repository:
        description: the repository name include the owner in `owner/repo_name` format
        required: true
      head_ref:
        description: the head sha
        required: true
      base_ref:
        description: the base ref
        required: true
      installation_id:
        description: the installation id
        required: false
      resolver_url:
        description: the resolver url to pass results to
        required: true
      resolver_token:
        description: Optional resolver token for resolver service
        required: false
        default: ''

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Adding PR Url
        run: |
          echo '[${{ fromJSON(fromJSON(inputs.client_payload)).repo }}#${{ fromJSON(fromJSON(inputs.client_payload)).prContext.number }}](${{ fromJSON(fromJSON(inputs.client_payload)).prContext.url }}) - `${{ fromJSON(fromJSON(inputs.client_payload)).branch }}` by ${{ fromJSON(fromJSON(inputs.client_payload)).prContext.author }}' >> $GITHUB_STEP_SUMMARY

      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine
        with:
          full_repository: ${{ github.event.inputs.full_repository }}
          head_ref: ${{ github.event.inputs.head_ref }}
          base_ref: ${{ github.event.inputs.base_ref }}
          client_payload: ${{ github.event.inputs.client_payload }}
          installation_id: ${{ github.event.inputs.installation_id }}
          resolver_url: ${{ github.event.inputs.resolver_url }}
          resolver_token: ${{ github.event.inputs.resolver_token }}

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

GitHub Multi Org gitStream Setup

Setup gitStream for multi-org

Multi-org rules are ideal when you want to enforce consistent rules across every repo across multiple organizations on your server. You can define them by creating a special repository named cm under the cm organization in your GitHub Server where you can add automation files that will apply to all repositories across all organizations.

Prerequisite: Create a cm repo under the cm org and enable gitStream.

Multi-org automations need to be defined in a repo named cm inside the cm organization on your GitHub Server. Before continuing, you must create this repo and enable the gitStream app for it.

Required Configurations – gitStream

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

Configuration files go in the repo's root directory.
Unlike the setup instructions for a single repo, your .cm files should be placed in the repository's root directory.

# -*- mode: yaml -*-
manifest:
  version: 1.0

automations:
  linearb_ai_codereview:
    # Ai Code Review - Triggers only when PR is ready for review, see docs https://docs.gitstream.cm/execution-model/#action-level-execution-control
    on: [pr_created, pr_ready_for_review, merge]
    if:
      - {{ not is.bot }}
    run:
      - action: code-review@v1
        args:
          guidelines: |
            - Highlight **critical issues** only (correctness/logic, performance, security, maintainability blockers).
            - Skip nitpicks; ignore null-reference risks that are known to be validated earlier in this code path.
            - Keep suggestions short and actionable.

  pr_policy_low_noise:
    on: [pr_created, commit]
    if:
      - {{ not pr.draft }}
      - {{ not is.bot }}
    run:
      # AI description (updates PR body; not a comment)
      - action: describe-changes@v1
        args:
          concat_mode: append

      # Quiet labels
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ colors.red if (calc.etr >= 20) else (colors.yellow if (calc.etr >= 5) else colors.green) }}

      - action: add-label@v1
        when :  {{ pr.unresolved_threads }}
        args:
          label: "{{ pr.unresolved_threads | default(value=0) }} unresolved thread(s)"
          color: {{ colors.yellow }}

      - action: add-label@v1
        when: {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
        args:
          label: "missing-jira"
          color: {{ colors.red }}
          # further automations available with Jira webhook

      # Assign reviewers silently
      - action: add-reviewers@v1
        args:
          reviewers: {{ who.experts }}

      # ONE consolidated, updatable comment
      - action: add-comment@v1
        args:
          comment: |
            ## gitStream Summary — Low Noise (Staff Engineer focus)

            **AI PR Description:** Updated in the PR body above.
            **ETR:** {{ calc.etr }} min review
            **Unresolved threads:** {{ pr.unresolved_threads | default(value=0) }}

            ### Suggested Reviewers (auto-assigned)
            {{ who.experts }}

            ### Jira Reference
            {{ '✅ Found in title/description.' if (has.jira_ticket_in_title or has.jira_ticket_in_desc) else '⚠️ Missing Jira ticket. Please add one (e.g., `ABC-123` or an `atlassian.net/browse/...` link).' }}

            > Labels/reviewers were applied quietly to keep this PR clean.

# ----------------- config -----------------
calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title       | includes(regex=r/\b[A-Za-z][A-Za-z0-9_]+-\d+\b/) }}
  jira_ticket_in_desc:  {{ pr.description | includes(regex=r/\b[A-Za-z][A-Za-z0-9_]+-\d+\b/) }}

who:
  experts: {{ repo | codeExperts(gt=10, top=5) }}

is:
  bot: {{ pr.author | match(list=['github-actions','_bot_','[bot]','dependabot','gitstream-cm','dayforce-global-sonar-integration','prvalidation','aida-bot']) | some }}

colors:
  red:    'b60205'
  yellow: 'fbca04'
  green:  '0e8a16'

GitHub Actions

# Code generated by gitStream GitHub app - DO NOT EDIT

name: gitStream workflow automation
run-name: |
  /:\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}

on:
  workflow_dispatch:
    inputs:
      client_payload:
        description: The Client payload
        required: true
      full_repository:
        description: the repository name include the owner in `owner/repo_name` format
        required: true
      head_ref:
        description: the head sha
        required: true
      base_ref:
        description: the base ref
        required: true
      installation_id:
        description: the installation id
        required: false
      resolver_url:
        description: the resolver url to pass results to
        required: true
      resolver_token:
        description: Optional resolver token for resolver service
        required: false
        default: ''

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Adding PR Url
        run: |
          echo '[${{ fromJSON(fromJSON(inputs.client_payload)).repo }}#${{ fromJSON(fromJSON(inputs.client_payload)).prContext.number }}](${{ fromJSON(fromJSON(inputs.client_payload)).prContext.url }}) - `${{ fromJSON(fromJSON(inputs.client_payload)).branch }}` by ${{ fromJSON(fromJSON(inputs.client_payload)).prContext.author }}' >> $GITHUB_STEP_SUMMARY

      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine
        with:
          full_repository: ${{ github.event.inputs.full_repository }}
          head_ref: ${{ github.event.inputs.head_ref }}
          base_ref: ${{ github.event.inputs.base_ref }}
          client_payload: ${{ github.event.inputs.client_payload }}
          installation_id: ${{ github.event.inputs.installation_id }}
          resolver_url: ${{ github.event.inputs.resolver_url }}
          resolver_token: ${{ github.event.inputs.resolver_token }}

Success

Once finished, the GitHub Action will process all PRs to repositories across all organizations on your server. Your cm repo under the cm org should have a file directory that looks like this:

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

GitHub Enterprise Setup

When running gitStream on GitHub Enterprise, your runners often do not have direct internet access. In that case, you must manually make the required GitHub Actions available to your runners.

gitStream action: linear-b/gitstream-github-action
Official GitHub actions such as:
- actions/checkout
- actions/setup-node
- actions/github-script
- Any other actions referenced in your workflows

You'll need to pull or mirror these actions to a location accessible to your self-hosted runners (for example, by cloning them into an internal GitHub Enterprise organization or code-hosted mirror) so the runner can resolve and execute them.

Verify

Check that everything is wired correctly

In LinearB, confirm the GitHub Server gitStream connection shows as connected.
In GitHub Server:
- Confirm the GitHub App is installed on the target org(s) and repos.
- Confirm each repo has:
  - A .cm file (such as .cm/gitstream.cm), and
  - A .github/workflows/gitstream.yml workflow.
Open a test pull request and check:
- That the gitStream workflow runs.
- That you see gitStream checks, labels, or comments according to your rules.

Troubleshooting

Problem	Possible cause	How to fix
gitStream never appears on PRs	GitHub App not installed on that repo or workflow missing	Verify the app installation includes the repo and confirm `.github/workflows/gitstream.yml` exists on the default branch.
App can’t connect to LinearB	Network/firewall restrictions	Ensure your GitHub Server can reach the required IPs and that the Webhook URL from LinearB is correct.
Workflow runs but no automations fire	No matching rules in `.cm` file or misconfigured conditions	Test with a simple, always-on rule and verify the `.cm` file is in the correct location.
Timeouts / long execution	Large repos or deep history causing long clones	Consider shallow clones (if supported by your setup) or limiting automations that require full history.

FAQs

Do I have to install the app on all organizations?
No. You can install it on only the orgs that use gitStream. You can expand later.

Can I use both org-level and repo-level rules?
Yes. Org-level rules in the cm repo apply broadly. Repo-level rules override org rules when they share the same automation identifier.

Does gitStream change my code?
No. gitStream reads code and metadata to evaluate rules, then updates PR metadata (checks, labels, comments, approvals) but does not modify source files.

Next steps