gitStream - GitHub Cloud Installation

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.

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.

# -*- 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'

          

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

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.

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

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

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. [oai_citation:4‡gitStream Documentation](https://docs.gitstream.cm/troubleshooting/?utm_source=chatgpt.com)

Before you start

• Open at least one PR so the gitStream check appears in GitHub’s recent status checks list. [oai_citation:5‡gitStream Documentation](https://docs.gitstream.cm/github-installation/)

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.