Skip to main content
Deutsch (Deutschland) Español Français Hebrew (Israel) Italiano Português

GitHub Cloud Installation

Heather Hazell
Updated

Install gitStream on GitHub Cloud to enable PR automation, AI-aware workflows, and LinearB’s AI Insights. Use this guide to install gitStream on GitHub Cloud, add the required files, and verify that automations are running on your pull requests.

Time Required: 3–5 minutes 
Difficulty: Easy

Overview

gitStream is installed as a GitHub App and evaluates automation rules defined in .cm files inside your repositories. On GitHub Cloud you can:

  • Install gitStream for a single repo, a subset of repos, or your entire organization.
  • Keep rules in one repo (org-wide) or per-repo for more granular control.
  • Trigger automations using a GitHub Actions workflow.

Before you begin

Prerequisites

  • GitHub Cloud organization with admin permissions to install apps.
  • Repository (or “cm” org repo) where you will store gitStream rules.
  • LinearB Admin or Editor permissions.
  • Optional but recommended: a LinearB account to view metrics powered by gitStream.

Expected time

  • Initial installation: ~5 minutes.
  • First rules + workflow file: ~5–10 minutes.

Step 1. Install the gitStream GitHub App

Install from the GitHub Marketplace

  1. Go to the gitStream GitHub App page (GitHub Marketplace).
  2. Click Install.
  3. Select the GitHub organization where you want to install gitStream.
  4. Choose whether to install gitStream on:
    • All repositories – recommended, ensures new repos are covered automatically; or
    • Only selected repositories – if you want to pilot gitStream on a subset of repos first.
  5. Confirm and complete the installation.

You can change which repositories gitStream is installed on at any time in the GitHub App settings.

Step 2. Configure a single repository (or see step 3 for recommended org configuration)

2.1 – Add a gitStream configuration file

In each repository where you want gitStream rules:

  1. In your repo’s default branch (usually main or master), create a directory named .cm at the root of the repo.
  2. Inside .cm, create a file such as gitstream.cm (any name is fine as long as it ends with .cm).
  3. Add your automations to this file in YAML format.

2.1 – Add a gitStream rules file

In each repository where you want gitStream rules:

  1. In your repo’s default branch (usually main or master), create a directory named .cm at the root of the repo.
  2. Inside .cm, create gitstream.cm.
  3. Paste the low-noise starter configuration below.
Example: low-noise starter configuration
# -*- mode: yaml -*-

manifest:

  version: 1.0

automations:

  linearb_ai_codereview:

    # Ai Code Review - Triggers only when PR is ready for review

    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'

This configuration is intentionally low-noise and matches the official GitHub installation example. 

You can add more automations or split them into multiple .cm files as your usage grows.

2.2 – Add the GitHub Actions workflow

gitStream uses a GitHub Actions workflow to evaluate rules on pull requests.

  1. In the same repository, create the file .github/workflows/gitstream.yml in the default branch.
  2. Paste the standard gitStream workflow configuration provided when you install the app or from the gitStream docs.

Standard workflow structure (simplified)

# .github/workflows/gitstream.yml
name: gitStream workflow automation

on:
  workflow_dispatch:
    inputs:
      client_payload:
        required: true
      full_repository:
        required: true
      head_ref:
        required: true
      base_ref:
        required: true
      installation_id:
        required: true

jobs:
  gitStream:
    runs-on: ubuntu-latest
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine

Working with large monorepos?
Use the @v2-lite version of the action to perform a shallow clone and reduce execution time. Note that some automations that depend on deep Git history may not work in lite mode.

Step 3. (Recommended) Configure organization-wide rules

Use a central “cm” repo for org-wide policies

If you want consistent rules across many repos, you can define organization-level automations in a dedicated cm repository.

  1. In your GitHub organization, create a new repo named cm.
  2. Install gitStream on this repo (it must be included in the GitHub App installation).
  3. In the cm repo’s default branch:
    • Create a file such as gitstream.cm in the repo root (no .cm directory needed).
    • Create .github/workflows/gitstream.yml with the same workflow configuration as above.

Any automation defined here will apply to all repositories where gitStream is installed, unless a repository defines its own automation with the same identifier (repo rules override org rules).

Step 4. Verify gitStream is working

Quick verification checklist

  • Confirm the gitStream GitHub App is installed for the org and the target repo(s).
  • Ensure the repo contains:
    • .cm/gitstream.cm (or other .cm file), and
    • .github/workflows/gitstream.yml.
  • Open a new pull request against the default branch.
  • Check the PR checks and comments:
    • You should see gitStream checks and, depending on your rules, labels or comments added automatically.

Step 5. (Optional) Block merges by requiring gitStream checks

Set gitStream as a required check

If you use automations that should block merges (for example, setting required approvals), you must add gitStream as a required status check in GitHub branch protection rules.

Before you start

  • Open at least one PR so the gitStream check appears in GitHub’s recent status checks list.
  1. Go to your repository Settings.
  2. Select Code and automation > Branches.
  3. Edit or create a Branch protection rule for your default branch.
  4. Enable Require status checks to pass before merging.
  5. Search for status checks in the last week for this repository.
  6. Select gitStream.cm as a required check.

Gotchas

  • PR must not be a draft if your rule excludes drafts.
  • Bots are often excluded by default (ensure authors aren’t matched as bots).
  • Repo permissions matter: you must install the app on the same repos where your `.cm` folder lives.
  • GitHub’s “Require Status Checks” can block merges if you reference a gitStream check incorrectly.
  • YAML must live under .cm/ at the root of the repository.
  • To use describe-changes@v1, branches must contain commits.

Troubleshooting

Problem Possible cause How to fix
No gitStream checks on PRs Workflow file missing or gitStream app not installed on that repo
  • Ensure YAML exists in .cm/ at the repo root.
  • Confirm the GitHub App is installed for the correct repos.
  • Check whether the PR is a draft (drafts may be excluded).
  • Confirm the PR author is not classified as a bot.
Workflow runs but no automations fire No matching rules in the .cm file Verify the conditions in your automations and test with a PR that clearly matches those conditions.
Timeouts or long run times on large repos Full clone takes too long in GitHub Actions Switch to the @v2-lite gitStream action for a shallow clone, or narrow the repo paths if possible.

FAQs

Do I need both repo-level and org-level rules?
No. You can use only repo-level rules, only org-level rules (via the cm repo), or a combination. Repo rules override org rules when they use the same automation identifier.

Can I start with just one or two repositories?
Yes. Many teams start with a pilot repo or team, then expand gitStream to additional repos after validating value and fine-tuning noise levels.

Does gitStream modify my code?
gitStream reads your code and metadata to evaluate rules and update PR state (comments, labels, statuses, and optional approvals/merges). It does not edit source files.

 

Next steps

Related articles