gitStream Quickstart

This page contains common gitStream configurations that are a great place to begin adopting a continuous merge mindset with gitStream. If you haven't already, you'll need to install gitStream to your GitHub or GitLab organization before you can use these automations

Build your first gitStream automation in as little as two minutes.

These example are complete gitStream configuration files that you can download directly via the buttons below the examples and upload to the .cm directory of your repo. Alternatively, you can copy and paste the individual automations, but make sure you include all required declarations and any related custom expressions from the configuration to ensure everything works properly.

Improve PR Context with Label Automation

This CM automation contains a collection of workflows to automatically apply labels that to provide deeper context to code reviewers to help them more quickly triage and address incoming requests for reviews. Ideally, you should implement these automations across your entire git organization to maximize developer usage.

The following example includes workflow automations to do the following:

Apply color-coded labels that estimate how long it takes to review the PR.
Flag PRs that lack required references to Jira tickets. Check out the gitStream integrations page for more examples of third-party project management tools gitStream integrates with.
Label PRs that have unresolved change requests, or delete code.

Label management quickstart

Label Management with gitStream

# -*- mode: yaml -*-
# +----------------------------------------------------------------------------+
# | /:\ gitStream: Workflow automation for the code review process.            |
# +----------------------------------------------------------------------------+
# | This file contains one or more /:\ gitStream automations:                  |
# | https:// docs.gitstream.cm                                                 |
# |                                                                            |
# | gitStream uses YAML syntax with nunjucks templating via Jinja 2.           |
# |                                                                            |
# | Automations follow an "if this, then that" execution format.               |
# | More info here: https://docs.gitstream.cm/how-it-works/                    |
# |                                                                            |
# +----------------------------------------------------------------------------+

# /:\ gitStream Reference Docs: 
#    Context Variables: https://docs.gitstream.cm/context-variables/
#    Filter Functions: https://docs.gitstream.cm/filter-functions/
#    Automation Actions: https://docs.gitstream.cm/automation-actions/

manifest:
  version: 1.0

# +----------------------------------------------------------------------------+
# | Automations
# +----------------------------------------------------------------------------+

automations:
  # Apply color coded labels to PRs based on the estimated time to review.
  # https://docs.gitstream.cm/automations/provide-estimated-time-to-review/
  estimated_time_to_review:
    if:
      - true
    run:
      - 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 ) }}

  # Flag PRs that are missing a Jira ticket reference in the title or description.
  # https://docs.gitstream.cm/integrations/jira/
  label_missing_jira_info:
    if:
      - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
    run:
      - action: add-label@v1
        args:
          label: "missing-jira"
          color: {{ colors.red }}

  # Flag PRs that have unresolved comment threads.
  # https://docs.gitstream.cm/automations/standard/label-management/label-unresolved-threads/
  label_unresolved_threads:  
    if:
      - {{ pr.status == 'open' }}  
      - {{ pr.unresolved_threads }}
    run:
      - action: add-label@v1
        args:
          label: 🚨 {{ pr.unresolved_threads }} Unresolved Thread(s)
          color: {{ colors.yellow }}  

  # Flag PRs that delete files to highlight potential refactors that need extra scrutiny.
  # https://docs.gitstream.cm/automations/label-deleted-files/
  flag_deleted_files:
    if:
      - {{ has.deleted_files }}
    run: 
      - action: add-label@v1
        args:
          label: 🗑️ Deleted files
          color: {{ colors.orange }}


# +----------------------------------------------------------------------------+
# | Custom Expressions                                                         |
# | https://docs.gitstream.cm/how-it-works/#custom-expressions                 |
# +----------------------------------------------------------------------------+

# https://docs.gitstream.cm/filter-functions/#estimatedreviewtime
calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}
  deleted_files: {{ source.diff.files | map(attr='new_file') | match(term='/dev/null') | some }}


# These are all of the colors in GitHub's default label color palette.
colors:
  red: 'b60205'
  orange: 'd93f0b'
  yellow: 'fbca04'
  green: '0e8a16'
  blue: '1d76db'
  purple: '5319e7'

Download this example as a CM file.

Automatically Route PR Reviews

If you're ready to begin automatically routing PRs for review, the best solution is to classify PRs according to the amount of risk they create. This next example classifies PRs into one of three categories based on the changes they contain and automatically establishes review criteria.

The following example includes workflow automations to do the following:

Recommend the most knowledgeable code experts to review the PR.
Automatically approve low-risk PRs to docs, testing, or code formatting.
Define criteria for when PRs need one or more reviews.
Label PRs that are available to be cherry picked to merge into the next release.

Assign Code Experts Examples

Review Routing with gitStream

# -*- mode: yaml -*-
# +----------------------------------------------------------------------------+
# | WARNING: This file controls repo automations, use caution when modifying   |
# +----------------------------------------------------------------------------+
# | This file contains one or more /:\ gitStream automations:                  |
# | https:// docs.gitstream.cm                                                 |
# |                                                                            |
# | gitStream uses YAML syntax with nunjucks templating via Jinja 2.           |
# |                                                                            |
# | Automations follow an "if this, then that" execution format.               |
# | More info here: https://docs.gitstream.cm/how-it-works/                    |
# |                                                                            |
# +----------------------------------------------------------------------------+

# /:\ gitStream Reference Docs: 
#    Context Variables: https://docs.gitstream.cm/context-variables/
#    Filter Functions: https://docs.gitstream.cm/filter-functions/
#    Automation Actions: https://docs.gitstream.cm/automation-actions/

manifest:
  version: 1.0

# +----------------------------------------------------------------------------+
# | Customize This Section                                                     |
# +----------------------------------------------------------------------------+

# Change review_team to match your organization or repo's primary review team. 
# The format is Git Organization Name / Team Name
review_team: 'my-org/team-name'

# List of files that should trigger a sensitive file change review.
sensitive:
  - App.tsx
  - AppRoot.tsx

# Files to exclude from gitStream automations.
config:
  ignore_files:
    - 'yarn.lock'
    - 'ios/*.lock'
    - 'android/*.lock'

# Set long_review_threshold to the number of minutes that should trigger extra review requirements.
long_review_threshold: 5

# +----------------------------------------------------------------------------+
# | Automations
# +----------------------------------------------------------------------------+

automations:

  # Post a comment that recommends reviewers based on their knowledge of the files in the PR.
  # https://docs.gitstream.cm/automations/standard/explain-code-experts/
  explain_code_experts:
    # Alternatively, if you only want to trigger when the slash command `/gitstream suggest-reviewers` is included in a comment,
    # change '- true' to '- {{ (pr.comments | match(attr='content', term='/gitstream suggest-reviewers') | some) }}'
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10

  # Automatically approve changes that only affect formatting, documentation, tests, or images
  # https://docs.gitstream.cm/automations/approve-safe-changes/
  approve_safe_changes:
    if:
      - {{ is.safe_change }}
    # Apply a safe change label, approve the PR and explain why in a comment.
    run: 
      - action: add-label@v1
        args:
          label: 'Safe Change'
          color: {{ colors.green }}
      - action: approve@v1
      - action: add-comment@v1
        args:
          comment: |
            This PR is considered a safe change and has been automatically approved.

  # Set criteria for PRs that only need one reviewer.
  # This helps reduce the review burden for low-risk PRs.
  require_one_review:
    if:
      - {{ not has.sensitive_files }}
      - {{ is.quick_review }}
      - {{ approvals.zero }}
    run:
      - action: add-label@v1
        args: 
          label: ⏳ Waiting for 1 reviewer
          color: {{ colors.yellow }}
      - action: add-reviewers@v1
        args:
          reviewers: [{{ review_team }}]
          unless_reviewers_set: true
      - action: set-required-approvals@v1
        args:
          approvals: 1

  # Set criteria for PRs that need extra reviewers.
  # This helps bring in extra scrutiny for large PRs or PRs that touch sensitive parts of the code.
  require_two_reviews:
    if:
      - {{ is.long_review or has.sensitive_files }}
      - {{ approvals.ltTwo }}
    run:
      - action: add-label@v1
        args: 
          label: {{ '⏳ Waiting for 2 reviewers' if (approvals.zero) else '⏳ Waiting for 1 reviewer' }}
          color: {{ colors.yellow }}
      - action: add-reviewers@v1
        args:
          reviewers: [{{ review_team }}]
          unless_reviewers_set: true
      - action: set-required-approvals@v1
        args:
          approvals: 2

  # Flag low-risk PRs that are ready to merge.
  flag_quick_review_merge:
    if:
      - {{ not has.sensitive_files }}
      - {{ is.quick_review }}
      - {{ not has.do_not_merge_label }}
      - {{ approvals.gtZero }}
    run:
      - action: add-label@v1
        args:
          label: ✌️ Ready to merge
          color: {{ colors.green }}

  # Flag higher risk PRs that are ready to merge.
  flag_large_review_merge:
    if:
      - {{ is.long_review or has.sensitive_files }}
      - {{ approvals.gtOne }}
    run:
      - action: add-label@v1
        args:
          label: ✌️ Ready to merge
          color: {{ colors.green }}


# +----------------------------------------------------------------------------+
# | Custom Expressions                                                         |
# | https://docs.gitstream.cm/how-it-works/#custom-expressions                 |
# +----------------------------------------------------------------------------+

# https://docs.gitstream.cm/filter-functions/#estimatedreviewtime
calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  sensitive_files: {{ files | match(list=sensitive) | some }}
  do_not_merge_label: {{ pr.labels | match(term='Do not merge') | some }}

is:
  safe_change: {{ (source.diff.files | isFormattingChange) or (files | allDocs) or (files | allTests) or (files | allImages) }}
  quick_review: {{ files | length <= 7 and calc.etr <= long_review_threshold }}
  long_review: {{ files | length > 7 or calc.etr > long_review_threshold }}

approvals:
  zero: {{ pr.approvals | length == 0 }}
  gtZero: {{ pr.approvals | length > 0 }}
  gtOne: {{ pr.approvals | length > 1 }}
  ltTwo: {{ pr.approvals | length < 2 }}

# These are all of the colors in GitHub's default label color palette.
colors:
  red: 'b60205'
  orange: 'd93f0b'
  yellow: 'fbca04'
  green: '0e8a16'
  blue: '1d76db'
  purple: '5319e7'

Download this example as a CM file.

Next Step

For a more detailed list of automations, check out the gitStream integrations page or automation library.