---

gitStream is a workflow automation tool to optimize your code review process.
Add context to Pull Requests, find code experts for reviews, and automate the merge process to maximize developer productivity!

Table of Contents

• Why gitStream and not GitHub Actions?
• Meet gitStream Bot: Your Code Review Sidekick!
• Users loving gitStream
• Getting started in two min
• The gitStream Dashboard

Why gitStream and not GitHub Actions?

Think of gitStream as the Robin to your GitHub Actions Batman. It’s not here to replace GitHub Actions or other CI/CD pals like CircleCI or Jenkins. Instead, gitStream is optimized to enhance the continuous merge process for open-source projects with multiple contributors.

Meet gitStream Bot: Your Code Review Sidekick!

gitStream bot can shorten your code review cycles by a 40% with built-in automation like:

• 🏷️ Enforce Semantic PR Titles - enforce pull request naming conventions
• 📊 Calculate percent new code - post a comment with the percentage of new code
• 🎯 Assign code experts - assign recommended reviewers based on code components
• 🕰️ Provide estimated time to review - label PRs estimated number of minutes it would take to review

Users loving gitStream

From small side projects to complex codebases, all types of open source communities love gitStream:

• gradle/gradle 15.2k ⭐
• gitcoinco/grants-stack 250 ⭐
• vim-zz/swordfish-rs 50 ⭐
• linear-b/gitstream (Yes, PRs to gitStream docs are also checked with gitStream 🤯)

Getting started in two min

1️⃣ Install the GitHub app
gitStream is a verified GitHub app on the marketplace, audited and approved by the GitHub Security team.

2️⃣ Create a .cm/gitstream.cm automations file in your repository
This file will contain a YAML configuration that determines the automations that run on every PR to the repository's default branch (usually master or main).

For example, this automation file will add a label with an estimated time to review for every new pull request:

# -*- mode: yaml -*-
# This example configuration for provides basic automations to get started with gitStream.
# View the gitStream quickstart for more examples: https://docs.gitstream.cm/quick-start/
manifest:
  version: 1.0
automations:
  # Add a label indicating how long it will take to review the PR.
  estimated_time_to_review: 
    if:
      - true
    run:
      - action: add-label@v1
      # etr is defined in the last section of this example
        args:
          label: "{{ calc.etr }} min review"
          color: {{ 'E94637' if (calc.etr >= 20) else ('FBBD10' if (calc.etr >= 5) else '36A853') }}
  # Post a comment that lists the best experts for the modified files.
  explain_code_experts:
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10 
# The next function calculates the estimated time to review and makes it available in the automation above.
calc:
  etr: {{ branch | estimatedReviewTime }}

3️⃣ Create a .github/workflows/gitstream.yml file to trigger gitStream on every PR
Copy-paste the following configuration file (no need to edit) and place it in your repository default branch:

# 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: 5
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v1
        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 }}

How to ensure uniformity across all repositories?

By creating a special repository named cm within your GitHub organization and placing your automation files there, you'll seamlessly apply the same rules to all repositories under the organization’s umbrella 🌂 Check out our docs for more detailed info: https://docs.gitstream.cm/github-installation/

The gitStream Dashboard

Imagine having a high-tech control room where you can see every move, every automation executed, and its impact—all in one place. Welcome to the gitStream Dashboard!

• 👀 Get a Bird's-Eye View: Observe all executed automations and their outcomes from a single, intuitive interface.
• 📊 Analyze & Optimize: Delve into detailed reports that help you understand the effectiveness of your automations, enabling you to fine-tune them for even smoother workflows.

---

🔼 Back to top