gitStream - GitHub Server Installation (Custom App)

1. Log in to the LinearB app.
2. Go to Settings → Git.
3. Locate your GitHub Server integration.
4. Click Connect gitStream (or equivalent gitStream setup button).
5. 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.

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

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.

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.

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.

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

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

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

1. In GitHub Server, go to your organization settings and open GitHub Apps / Third-party access.
2. Select the gitStream app you just created.
3. Install the app:
   • Either on a single organization, or
   • On multiple orgs (multi-org support) if your company uses several GitHub Server orgs.
4. 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.

Single Repo Setup

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 Setup

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 Setup

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

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, 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

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