diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/404.html b/404.html new file mode 100644 index 000000000..a42110ccc --- /dev/null +++ b/404.html @@ -0,0 +1 @@ +
Actions are the end results of the automation described in your .cm
file.
Legend
The icons indicate the availability status of each action.
send-http-request
is executed immediately after the evaluation of the condition. For all other actions, gitStream executes the actions in the order they are listed per automation. If an action result fails, the following actions will not be executed.
add-comment
add-github-check
add-label
add-labels
add-reviewers
explain-code-experts
approve
close
merge
send-http-request
send-slack-message
set-required-approvals
request-changes
require-reviewers
run-github-workflow
Note
Multiple actions can be listed in a single automation. The actions are invoked one by one.
Arguments values a dynamic value is supported using expressions based on Jinja2 syntax, and includes gitStream context variables, for example:
automations:
+ pr_complexity:
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: "Estimated {{ branch | estimatedReviewTime }} minutes to review"
+
add-comment
This action, once triggered, adds a comment to the PR.
This is a manged action, when a PR updates, the existing comments that were added by gitStream are re-evaluated and those that are not applicable are removed.
Args | Usage | Type | Description |
---|---|---|---|
comment | Required | String | Sets the comment, markdown is supported |
automations:
+ senior_review:
+ if:
+ - {{ files | match(term='core/') | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Core service update
+ (Updates API)
+
add-github-check
This action, once triggered, adds a completed
check with the specified conclusion to the listed checks in the PR.
Args | Usage | Type | Description |
---|---|---|---|
check_name | Required | String | The check name to be added to the checks list on gitHub |
conclusion | Required | String | The conclusion of the check. The value is one of the following: action_required , cancelled , timed_out , failure , neutral , skipped , success |
automations:
+ # Skip UI checks if the PR doesn't have a UI code changes
+ skip_ui_check:
+ if:
+ - {{ not has.fe_code_changes }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: FE-tests
+ conclusion: skipped
+has:
+ fe_code_changes: {{ files | match(regex=r/frontend\//) | some }}
+
add-label
This action, once triggered, adds a label to the PR.
This is a manged action, when a PR updates, the existing labels that were added by gitStream are re-evaluated and those that are not applicable are removed.
Args | Usage | Type | Description |
---|---|---|---|
label | Required | String | The label text any string can work |
color | Optional | String | The color in hex, for example: 'FEFEFE' (you can also add # prefix #FEFEFE ) |
automations:
+ senior_review:
+ if:
+ - {{ files | match(term='api/') | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: api-change
+
add-labels
This action, once triggered, adds a list of labels to the PR.
This is a manged action, when a PR updates existing labels that were added by gitStream are re-evaluated and those that are not applicable are removed.
Args | Usage | Type | Description |
---|---|---|---|
labels | Required | [String] | The list of text labels |
add-reviewers
This action, once triggered, sets a specific reviewer.
Args | Usage | Type | Description |
---|---|---|---|
reviewers | Required | [String] | Sets required reviewers. Supports user names and teams. Teams notated by adding a prefix with the owner name e.g. owner/team |
team_reviewers | Optional | [String] | Sets required team reviewers without a prefix team |
unless_reviewers_set | Optional | Bool | When true , the reviewers are not added if the PR has already assigned reviewers. It is set to false by default |
fail_on_error | Optional | Bool | When true , trying to assign illegal reviewers shall fail the automation, when false these errors are silently ignored. It is set to true by default |
wait_for_all_checks | Optional | Boolean | By default false . When true , the action will add reviewers only if all checks (except gitStream) are completed with neutral , skipped , or success conclusion |
automations:
+ senior_review:
+ if:
+ - {{ files | match(term='src/ui/') }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: [popeye, olive, acme/team-a]
+
Enable Team Write Access
If you want to assign teams as PR reviewers, you need to first make sure the team has write access to the repo in via your organization's settings. For more info, refer to the GitHub instructions for managing team review settings.
explain-code-experts
This action, shall add a comment with codeExperts suggestion. If the comment already exists, the comment shall be edited.
Args | Usage | Type | Description |
---|---|---|---|
lt | Optional | Integer | Filter the user list, keeping those below the specified threshold |
gt | Optional | Integer | Filter the user list, keeping those above the specified threshold |
automations:
+ code_experts:
+ if:
+ - true
+ run:
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
approve
This action, once triggered, approves the PR for merge.
This is a manged action, when a PR updates existing approval by gitStream is re-evaluated and removed if no longer applicable.
automations:
+ small_change:
+ if:
+ - {{ source.diff.files | isFormattingChange }}
+ run:
+ - action: approve@v1
+
close
This action, once triggered, close the PR without merging.
automations:
+ close_ui_changes_by_non_ui:
+ if:
+ - {{ files | match(regex=r/src\/views/) | some }}
+ - {{ pr.author_teams | match(term='ui-team') | nope }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Please contact a member of `ui-team` team if you need to make changes to files in `src/views`
+ - action: close@v1
+
merge
Once triggered, merge the PR if possible. It can be set to wait for all checks to pass or only required ones.
Args | Usage | Type | Description |
---|---|---|---|
wait_for_all_checks | Optional | Boolean | By default false , so only Required checks can block merge, when true the action will merge after all checks are completed with neutral , skipped , or success conclusion (except gitStream itself) |
rebase_on_merge | Optional | Boolean | By default false , when merging use rebase mode |
squash_on_merge | Optional | Boolean | By default false , when merging use squash mode |
automations:
+ small_change:
+ if:
+ - {{ files | allDocs }}
+ run:
+ - action: merge@v1
+ args:
+ rebase_on_merge: true
+
send-http-request
The action, once triggered, sends an HTTP request to the specified URL
Args | Usage | Type | Description |
---|---|---|---|
url | Required | String | The request URL |
method | Optional | String | By default GET , the request method |
headers | Optional | [String] | Empty by default ([] ), Key-Value list of strings, which will be sent as the HTTP headers |
user | Optional | String | Empty by default, format: 'username:password' . If used - adds a Basic-auth HTTP header, by setting the Authorization header. Using this arg will override any existing Authorization header that was set using headers |
body | Optional | String | Empty by default, the data to be sent as the request body. Only applicable for request methods PUT , POST , DELETE , and PATCH |
timeout | Optional | String | Empty by default (no timeout), the number of milliseconds before the request times out. When the time out is reached, the request will be aborted |
automations:
+ send_webhook:
+ if:
+ - true
+ run:
+ - action: send-http-request@v1
+ args:
+ url: "http://WEBHOOK_URL"
+ method: POST
+ headers: '{"Content-type": "application/json"}'
+ body: '{"text": "Hello, world!"}'
+
send-slack-message
The action, once triggered, sends a webhook with a message content to a Slack app. To use this action, create a Slack app with Incoming Webhooks enabled. gitStream uses the webhook URL to send the message.
Args | Usage | Type | Description |
---|---|---|---|
message | Required | String | The message content |
webhook_url | Optional | String | The webhook URL. Use the env variable to pass secrets |
automations:
+ send_slack:
+ if:
+ - true
+ run:
+ - action: send-slack-message@v1
+ args:
+ message: "Hello world :tada:."
+ webhook_url: "{{ slack_webhook }}"
+
+slack_webhook: {{ env.SLACK_WEBHOOK }}
+
set-required-approvals
This action, once triggered, blocks PR merge till the desired reviewers approved the PR. The actions fail the check to prevent the PR for merge.
Args | Usage | Type | Description |
---|---|---|---|
approvals | Required | Integer | Sets the number of required reviewer approvals for merge for that PR |
automations:
+ double_review:
+ if:
+ - {{ files | match(regex=r/agent\//) | some }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+
Attention
To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.
request-changes
This action, once triggered, request changes on the PR. As long as request change is set, gitStream will block the PR merge.
This is a manged action, when a PR updates existing change request by gitStream is re-evaluated and removed if no longer applicable.
Args | Usage | Type | Description |
---|---|---|---|
comment | Required | [String] | The desired request changes comment |
automations:
+ catch_deprecated:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/^[+].*oldFetch\(/') | some }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ You have used deprecated API `oldFetch`, use `newFetch` instead.
+
Attention
To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.
require-reviewers
This action, once triggered, requires a specific reviewer approval. The PR merge is blocked till approved by either of the listed users or teams.
Args | Usage | Type | Description |
---|---|---|---|
reviewers | Required | [String] | Sets required reviewers. Supports user names and teams. Teams notated by adding a prefix with the owner name e.g. owner/team . Merge is blocked till approved by either of the listed users |
also_assign | Optional | Bool | true by default, also assign the specified users as reviewers |
automations:
+ senior_review:
+ if:
+ - {{ files | match(regex=r/src\/ui\//) | some }}
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [popeye, olive, acme/team-a]
+
Attention
To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.
run-github-workflow
This action, once triggered, will start a workflow dispatch automation with the option to add a check to the list of checks in the PR
Args | Usage | Type | Description |
---|---|---|---|
workflow | Required | String | The ID or name of the workflow dispatch. |
owner | Optional | String | By default, the value of repo.owner context variable. The account owner of the repository. Case insensitive. |
repo | Optional | String | By default, the value of repo.name context variable. The name of the repository without the .git extension. Case insensitive. |
ref | Optional | String | By default, the value of branch.name context variable. The account owner of the repository. Case insensitive. |
inputs | Optional | String | By default, an empty list. Key-Value list with the arguments to provide to the workflow |
check_name | Optional | String | When added, after the workflow is complete, add the check name to the checks list on GitHub |
stop_ongoing_workflow | Optional | Boolean | By default, false . In case the workflow already runs on the branch, if true : cancel the ongoing workflow before running the newly dispatched workflow. If false : wait for the old workflow to finish before dispatching a new one |
on:
+ - commit
+
+automations:
+ run_workflow_dispatch:
+ if:
+ - {{ has.fe_code_changes }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ owner: {{ repo.owner }}
+ repo: {{ repo.name}}
+ workflow: .github/workflows/frontend-manual.yml
+ ref: {{ branch.name }}
+ check_name: FE-tests
+has:
+ fe_code_changes: {{ files | match(regex=r/frontend\//) | some }}
+
Attention
Require 2 reviewers for PRs that have more than 10 changed files in the src directory and the estimated time to review is 30 or more minutes.
Configuration Description
Conditions (all must be true):
src
directory.Automation Actions:
Additional Review for Large PRs
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ additional_review_for_large_pr:
+ if:
+ - {{ branch | estimatedReviewTime >= 30 }}
+ - {{ files | length >= 10 }}
+ - {{ files | match(regex=r/src\//) | some }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is a large change and requires 2 reviews.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically approve PRs that change docs, tests, and other safe assets.
Configuration Description
Conditions (all must be true):
Automation Actions:
safe-change
labelApprove Safe Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ safe_changes:
+ # Triggered for any changes that only affect formatting, documentation, tests, or images
+ if:
+ - {{ is.formatting or is.docs or is.tests or is.image }}
+ # Apply a safe change label, approve the PR and explain why in a comment.
+ run:
+ - action: add-label@v1
+ args:
+ label: 'safe-change'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is considered a safe change and has been automatically approved.
+
+# These custom expressions are used in the safe_changes automation
+is:
+ formatting: {{ source.diff.files | isFormattingChange }}
+ docs: {{ files | allDocs }}
+ tests: {{ files | allTests }}
+ image: {{ files | allImages }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically approve low-risk PRs from trusted teams.
Configuration Description
Conditions (all must be true):
docs
directorytech-writers
team.Automation Actions:
Approve Expert Team
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_team_by_directory:
+ # Triggered for PRs that only include changes to files inside the docs directory,
+ # and that are authored by someone on the tech-writers team.
+ if:
+ - {{ files | match(regex=r/docs\//) | every }}
+ - {{ pr.author_teams | match(term='tech-writers') }}
+ run:
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ Docs changes from the tech-writers team are automatically approved.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Label and approve PRs that only include tests, and post an explanation comment.
Configuration Description
Conditions (all must be true):
Automation Actions:
Approve Tests
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_tests:
+ if:
+ # Triggered for PRs that only include changes to tests
+ - {{ files | allTests }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'tests-only'
+ - action: add-comment@v1
+ args:
+ comment: |
+ This merge has been automatically approved because it only contains changes to tests.
+ - action: approve@v1
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Approve single-line changes to a single file.
Configuration Description
Conditions (all must be true):
Automation Actions:
single-line
label.name
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_tiny_change:
+ # Triggered for PRs that contain one file and one line.
+ if:
+ - {{ is.one_file and is.one_line }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'single-line'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it is only a single line
+
+changes:
+ # Sum all the lines added in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ # Sum all the line removed in the PR
+ deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
+
+is:
+ one_file: {{ files | length == 1 }}
+ one_line: {{ changes.additions - changes.deletions <= 1 }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically assign code reviewers based on directory structure. Optionally, you can substitue require-reviewers
for add-reviewers
to make review from the specified teams and individuals mandatory.
Configuration Description
Conditions (all must be true):
src/ui
directory.Automation Actions:
my-teamate
and a team named my-organization/ui-team
as reviewers. These should be customized to match your organization.Assign Reviewers by Directory
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_ui:
+ # Triggered for PRs that contain any changes to JavaScript files inside the `src/ui` directory.
+ if:
+ - {{ files | match(regex=r/src\/app\/auth\/.*/) | some}}
+ # Add a specified user and team as reviewers.
+ # Customize the reviewers to match your organization
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my-teamate, my-organization/security]
+ - action: add-comment@v1
+ args:
+ comment: |
+ The Security team has automatically been added for review because this PR contains changes to components inside `/src/app/auth`
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Assign PR reviewer based on the owner team membership.
You can also omit the | first
filter to assign all teams the owner is member of.
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
This library of gitStream examples is meant to serve as a starting point for your automation. We encourage you to customize them for your project and organization.
How to use these examples.
These examples are all 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 configurations to ensure they work properly.
missing-tests
label to any PRs that lack updates to tests.These examples help you label PRs where Generative AI was used to generate code.
These examples help you follow your team's security best practices.
These examples provide useful components to use in other automations. These aren't intended to be used on their own; instead they act as a reference point for improving other automations.
Have a great idea for an automation that should be included in this library?
Submit your configuration on GitHub. We'll recognize your contribution publicly (if you want) and might even send you some special swag for your contribution.
Request changes when a PR includes one or more deprecated components.
Configuration Description
Conditions (all must be true):
Automation Actions:
deprecated-component
label to the PRChange Deprecated Components
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Request changes when a PR includes deprecated components.
+ # This requires the `item` custom expression found at the bottom of this file.
+ {% for item in deprecated %}
+ # Automation names must be unique, so this adds an iterator index to each instance
+ review_deprecated_component_{{ item.old }}:
+ # Triggered when any of the modified files use a deprecated component
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=item.regex) | some }}
+ # Apply a deprecated-component label, request changes, and post a comment with an explanation.
+ run:
+ - action: add-label@v1
+ args:
+ label: 'deprecated-component'
+ color: '#FF0000'
+ - action: request-changes@v1
+ args:
+ comment: |
+ `{{ item.old }}` component is deprecated, use `{{ item.new }}` instead
+ {% endfor %}
+
+# These are the deprecated files that are evaluated in catch_deprecated_components
+deprecated:
+ - regex: r/oldAPI/
+ old: oldAPI
+ new: newAPI
+ - regex: r/anotherOldAPI/
+ old: anotherOldAPI
+ new: anotherNewAPI
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
If a PR creates a new Lambda function, but lacks a description field, gitStream will request changes and post a comment that explains why.
Configuration Description
Conditions (all must be true):
Automation Actions:
lambda-missing-field
label to the PR.Change Missing Lambda Field
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Request changes when required Lambda information is missing from the PR.
+ catch_missing_lambda_info:
+ # Triggered for new Lambda functions that are missing a description field.
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/LambdaFunction/) | some }}
+ - {{ source.diff.files | matchDiffLines(regex=r/description:/) | nope }}
+ # Apply the lambda-missing-field label and request changes to the PR.
+ run:
+ - action: add-label@v1
+ args:
+ label: 'lambda-missing-field'
+ color: '#FF0000'
+ - action: request-changes@v1
+ args:
+ comment: |
+ New `LambdaFunction` must have `description:` field.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Close PRs to a specified directory if the PR author is not on an approved team.
Configuration Description
Conditions (all must be true):
/src/views
. Customize this value for your project.ui
team. Customize this value for your organization.Automation Actions:
Close Wrong Team by Directory
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Close PRs to restricted sections of the codebase if the PR author isn't on the correct team.
+ close_wrong_team_by_directory:
+ # Triggered when someone who isn't on the `ui` team submits a PR to change files inside /src/views
+ if:
+ - {{ files | match(regex=r/src\/views/) | some }}
+ - {{ pr.author_teams | match(term='ui') | nope }}
+ # Close the PR and post a comment explaining the next step.
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Please contact a member of the `ui` team if you need to make changes to files in `src/views`
+ - action: close@v1
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically label PRs that are missing references to Asana resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Asana Link
labelLabel Missing Asana
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_asana:
+ if:
+ - {{not (has.asana.ticket_in_title or has.asana.ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Asana Link"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated Asana resource.
+
+has:
+ asana:
+ ticket_in_title: {{ pr.title | includes(regex=r/asana-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/app\.asana.\com\/(\d+)\/(\d+)\/(\d+)\/(\d+)\/(\d+)/) }}
+
+colors:
+ red: 'b60205'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Provide automatic links to Asana cards that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Asana Card
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+provider: asana
+
+# Configure this to match your organization. It is used in tracker.asana.baseurl.
+asanaProject: 1234
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_asana:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ asana:
+ baseurl: https://app.asana.com/0/[asanaProject]/0/
+ pattern: r/asana-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically label PRs that are missing references to Azure Boards resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Azure Boards Link
labelLabel Missing Azure Boards
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_azure:
+ if:
+ - {{not (has.azure.ticket_in_title or has.azure.ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Azure Boards Link"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated resource in Azure Boards.
+
+has:
+ azure:
+ ticket_in_title: {{ pr.title | includes(regex=r/(\w+)-(\w+)-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/(dev\.azure\.com|(\w+)\.visualstudio\.com)\/(\w+)\/(\w+)\/_workitems\/edit\/(\d+)/) }}
+
+colors:
+ red: 'b60205'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Provide automatic links to Azure Boards resources that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Azure Boards Resource
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Configure these to match your organization.
+provider: azure
+# The name of your Azure organization
+orgName: org
+# The name of your Azure project
+azureProject: my_project
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_azure_boards:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ azure:
+ baseurl: https://dev.azure.com/[orgName]/[azureProject]/_workitems/
+ pattern: r/(\w+)-(\w+)-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically apply labels to PRs that are assisted by GitHub Copilot. You can apply labels based on a known list of Copilot users, PR tags, or by prompting the PR author to indicate if they used Copilot.
Automatically apply labels to PRs that are created by known users of generative AI coding tools.
Configuration Description
Conditions:
Automation Actions:
🤖 Copilot
label to the PRLabel by Contributors
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_genai:
+ # For all PRs authored by someone who is specified in the genai_contributors list
+ if:
+ - {{ pr.author | match(list=genai_contributors) | some }}
+ # Apply a label indicating the user has adopted Copilot
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
+genai_contributors:
+ - username1
+ - username2
+ - etc
+
Look for a specific tag in the PR title, description, comments or commit messages and if found add a label to the PR
Configuration Description
Conditions:
#copilot#
tag is found in any of the PR title, description, comments or commit messages for commits in the PRAutomation Actions:
🤖 Copilot
label to the PRLabel Copilot by Tag
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_copilot:
+ # Detect PRs that contain the text '#copilot#' in the title, description, comments, or commit messages
+ if:
+ - {{ copilot_tag.pr_title or copilot_tag.pr_desc or copilot_tag.pr_comments or copilot_tag.commit_messages }}
+ # Apply a label indicating the user has adopted Copilot
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
+copilot_tag:
+ pr_title: {{ pr.title | includes(regex=r/#copilot#/) }}
+ pr_desc: {{pr.description | includes(regex=r/#copilot#/) }}
+ pr_comments: {{ pr.comments | map(attr='content') | match(regex=r/#copilot#/) | some }}
+ commit_messages: {{ branch.commits.messages | match(regex=r/#copilot#/) | some }}
+
Prompt PR authors to indicate if they used Copilot for the PR and automatically label the PR if they did. This requires two separate automation files to handle posting the prompt and labeling accordingly.
Configuration Description
Conditions:
Automation Actions:
Ask the PR author about Copilot usage.
-*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+
+automations:
+ comment_copilot_prompt:
+ # Post a comment for all PRs to prompt the PR author to indicate whether they used Copilot to assist coding in this PR
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Please mark whether you used Copilot to assist coding in this PR
+
+ - [ ] Copilot Assisted
+ - [ ] Not Copilot Assisted
+
Configuration Description
Conditions:
Automation Actions:
🤖 Copilot
label to the PR Label PRs where the user indicated Copilot usage
-*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - comment_added
+ - commit
+ - merge
+
+automations:
+ # You should use this automation in conjunction with comment_copilot_prompt.cm
+ label_copilot_pr:
+ # If the PR author has indicated that they used Copilot to assist coding in this PR,
+ # apply a label indicating the PR was supported by Copilot
+ if:
+ - {{ pr.comments | filter(attr='commenter', term='gitstream-cm') | filter (attr='content', regex=r/\- \[x\] Copilot Assisted/) | some}}
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
Approve PRs from Dependabot
Conditions (all must be true):
Automation Actions:
approved-dependabot
label to the PRApprove Dependabot
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_dependabot:
+ if:
+ - {{ branch.name | includes(term="dependabot") }}
+ - {{ branch.author | includes(term="dependabot") }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: "approved-dependabot"
+ - action: merge@v1
+ args:
+ wait_for_all_checks: true
+ squash_on_merge: true
+
Automatically trigger GitHub Actions based on PR content like changed resources, source or target branch, slash commands, and more.
Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions by Branch
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+automations:
+ {% for item in pipelines %}
+ # Change pr.target to branch.name if you want to trigger on the source branch rather then the target branch.
+ dispatch_github_action_{{ item.name }}:
+ if:
+ - {{ pr.target | includes(term=item.branch_prefix) }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ workflow: .github/workflows/{{ item.workflow }}
+ check_name: {{ item.name }}
+ - action: add-label@v1
+ args:
+ label: {{ item.label }}
+ {% endfor %}
+
+
+pipelines:
+ - name: mobile_ci
+ label: Mobile CI
+ branch_prefix: 'mobile-'
+ workflow: mobile.yml
+ - name: backend_ci
+ label: Backend CI
+ branch_prefix: 'backend-'
+ workflow: 'backend.yml'
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Using Labels
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - label_added
+ - label_removed
+
+automations:
+ {% for item in pipelines %}
+ dispatch_github_action_{{ item.name }}:
+ if:
+ - {{ pr.labels | match(term=item.label) | some }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ workflow: .github/workflows/{{ item.workflow }}
+ check_name: {{ item.name }}
+ {% endfor %}
+
+pipelines:
+ - name: mobile-ci
+ label: Mobile CI
+ workflow: mobile.yml
+ - name: backend-ci
+ label: Backend CI
+ workflow: 'backend.yml'
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+automations:
+ {% for item in pipelines %}
+ dispatch_github_action_{{ item.name }}:
+ if:
+ - {{ files | match(list=item.resources) | some }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ workflow: .github/workflows/{{ item.workflow }}
+ check_name: {{ item.name }}
+ - action: add-label@v1
+ args:
+ label: {{ item.label }}
+ {% endfor %}
+
+
+pipelines:
+ - name: mobile-ci
+ label: Mobile CI
+ resources:
+ - 'src/android/'
+ - 'src/ios/'
+ workflow: mobile.yml
+ - name: backend-ci
+ label: Backend CI
+ resources:
+ - 'src/api/'
+ - 'src/services'
+ workflow: 'backend.yml'
+ - name: frontend-ci
+ label: Frontend CI
+ resources:
+ - 'src/app/'
+ workflow: 'frontend.yml'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically skip GitHub Actions based on branch names, modified resource, slash commands, and more.
Prerequisite Config for Required Statuses
If you want to skip a required status check, you will need to make sure that your branch protection is configured to allow gitStream to bypass status check requirements.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions by Branch
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+# Optionally, you can change pr.target to branch.name
+# if you want to trigger based on the source branch name rather then the target branch name.
+automations:
+ skip_github_action_branch:
+ if:
+ - {{ pr.target | includes(term='release') }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: staging-ci
+ conclusion: skipped
+ - action: add-comment@v1
+ args:
+ comment: |
+ [gitStream](https://docs.gitstream.cm) automatically skipped staging CI pipelines because this PR targets the release branch.
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Use Labels to Automatically Skip GitHub Actions
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - label_added
+ - label_removed
+
+automations:
+ skip_github_action_label:
+ if:
+ - {{ pr.labels | match(term='experimental') | some }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: production-ci
+ conclusion: skipped
+ - action: add-comment@v1
+ args:
+ comment: |
+ [gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this is labeled for experimental release.
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+automations:
+ skip_github_action_resource:
+ if:
+ - {{ files | match(term='docs/') | every }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: release-ci
+ conclusion: skipped
+ - action: add-github-check@v1
+ args:
+ check_name: mobile-ci
+ conclusion: skipped
+ - action: add-comment@v1
+ args:
+ comment: |
+ [gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this PR only contains docs changes.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Require more extensive reviews for large Golang changes that lack Godoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.⚠️ Missing Godoc
LabelReview Godoc
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ #Require more extensive reviews for large Golang changes that lack Godoc updates.
+ review_godoc_large:
+ if:
+ - {{ changes.additions > 100}}
+ - {{ source.diff.files | matchDiffLines(regex=r/^\/\/.*/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Godoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to Golang classes, but is missing updates to Godoc. Please double check for any necessary Godoc updates.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+
+colors:
+ yellow: 'fbca04'
+
Require Godoc for all new Golang classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Godoc
label.Enforce Godoc for New Golang Classes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_godoc_new_class:
+ if:
+ - {{ is.go and is.new }}
+ - {{ source.diff.files | match(attr='diff', regex=r/\/*[\s\S]*?\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing godoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ godoc is required for all Golang classes. Please add godoc to all new classes in this PR.
+
+is:
+ go: {{ files | extensions | match(regex=r/go/) | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Approve PRs that only contain changes to Godoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
📓 Godoc Only
labelReview Godoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ #Assign PRs that only affect godocs to the technical writing team and add docs label
+ review_godoc:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/^\/\/.*/) | every }}
+ - {{ files | extensions | match(regex=r/go/) | every }}
+
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓godoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [org/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
If a PR modifies the input parameters for a Java method, but not the associated Javadocs, notify reviewers to check for Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Javadoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_javadoc_input_parameters:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/\*\s@param/) | nope }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\b(public|protected|private|static|final|synchronized)?\s+\w+\s+\w+\s*\(([^)]*)\)\s*\{/) | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR modifies method input parameters, but is missing Javadoc changes. Please check to ensure no Javadoc changes are necessary.
+
Require more extensive reviews for large Java changes that lack Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/tech-writers
team.⚠️ Missing Javadoc
LabelReview Javadoc for Large Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ #Require more extensive reviews for large Java changes that lack Javadoc updates.
+ review_javadoc_large:
+ if:
+ - {{ changes.ratio > 25}}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Javadoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ # Sum all the line removed in the PR
+ deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
+ # Calculate the ratio of new code
+ ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}
+
+colors:
+ yellow: 'fbca04'
+
Unblock PRs that only change Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
org/tech-writers
team for optional review. 📓 Javadoc Only
labelReview Javadoc Changes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ # Assign PRs that only affect JavaDocs to the technical writing team and add docs label
+ review_javadoc:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\b(public|protected|private|static|final|synchronized)?\s+\w+\s+\w+\s*\(([^)]*)\)\s*\{/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓 Javadoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [org/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
Automatically request changes when someone creates a new Java class that lacks Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Javadoc
label.Review Javadoc Requirements for New Classes
manifest:
+ version: 1.0
+
+automations:
+ review_new_class_javadoc:
+ # Triggered for new Java files that lack Javadoc content.
+ if:
+ - {{ is.java and is.new }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Javadoc"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ This PR creates new Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.
+
+is:
+ java: {{ files | extensions | match(term='java') | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Label PRs that don't reference a Jira ticket in the title or description. This uses regex to detect Jira ticket formats in the title (e.g. ABC-1234), and URLs to Jira tickets in the description.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-jira
label.Label Missing Jira Info
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_jira_info:
+ # Triggered for PRs that don't have either a Jira ticket number in the title,
+ # or a link to a Jira ticket in the PR description.
+ if:
+ - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "missing-jira"
+ color: 'F6443B'
+
+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}/) }}
+
Provide automatic links to Jira issues that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Jira Card
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+provider: jira
+
+# Change this to the name of your Jira organization
+orgName: org
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_jira:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ jira:
+ baseurl: https://[orgName].atlassian.net/browse/
+ pattern: r/\b[A-Za-z]+-\d+\b/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Label the number of high, medium, and low risk vulnerabilities Jit reports for PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Jit Alerts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in reports %}
+ label_jit_{{ item.name }}:
+ if:
+ - {{ item.count > 0}}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'Jit: {{ item.count }} {{ item.name }} vulnerabilities'
+ color: {{ colors.red if (item.name == 'high') else (colors.orange if (item.name == 'medium' ) else colors.yellow) }}
+ {% endfor %}
+
+jit: {{ pr | extractJitFindings }}
+
+reports:
+ - name: high
+ count: {{ jit.metrics.HIGH }}
+ - name: medium
+ count: {{ jit.metrics.MEDIUM }}
+ - name: low
+ count: {{ jit.metrics.LOW }}
+
+colors:
+ red: 'b60205'
+ orange: 'd93f0b'
+ yellow: 'fbca04'
+
Manage review assignment for high and medium risk Jit security alerts.
Configuration Description
Review Jit High Alerts
Review Jit Medium Alerts
Review Jit Security Alerts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_jit_high_alerts:
+ if:
+ - {{ jit.metrics.HIGH > 0 }}
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [my-organization/security-team]
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR requires additional review because Jit reported one or more high risk vulnerabilities.
+ review_jit_medium_alerts:
+ if:
+ - {{ jit.metrics.MEDIUM > 0 }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR requires additional reviewers because Jit reported one or more medium risk vulnerabilities.
+
+
+jit: {{ pr | extractJitFindings }}
+
Notify your Security team when someone ignores a Jit vulnerability report and accepts the risk.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Ignore and Accept
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_jit_ignore_accept:
+ if:
+ - {{ pr.conversations | reject(attr='commenter', term='jit-ci') | filter(attr='content', term='#jit_ignore_accept') | some }}
+ run:
+
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my-organziation/security]
+ - action: add-label@v1
+ args:
+ label: '❕ Jit: Ignore - Accept Risk'
+ - action: add-comment@v1
+ args:
+ comment: |
+ The security team has been assigned for optional review because this PR ignores a Jit alert and accepts the associated risks.
+
+jit: {{ pr | extractJitFindings }}
+
Close PRs where Jit detects a secret and post a comment explaining steps to remedy the situation.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Security Control
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_jit_secret:
+ if:
+ - true
+ - {{ jit.vulnerabilities | match(attr='security_control', term='Secret Detection') | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Jit detects secrets in this PR. Please complete the following steps:
+ 1. Undo the commit with git reset and remove all secrets from the files you modified.
+ 2. Deactivate the secret in any locations its used and replace it with a new key
+ 3. Commit your changes and resubmit your PR.
+ - action: close@v1
+
+
+jit: {{ pr | extractJitFindings }}
+
Warn PR authors when they change JavaScript function or constructor input parameters without updating JSDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JSDoc Input Parameters
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_jsdoc_input:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/.*\s@param/) | nope }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\((?:.*\:.*\))/) | some }}
+
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR appears to modify method input parameters, but is missing JSDoc changes. Please check to ensure no JSDoc changes are necessary.
+
Require more extensive reviews for large JavaScript changes that lack JSDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.⚠️ Missing JSDoc
LabelReview JSDoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ #Require more extensive reviews for large Javascript changes that lack JSDoc updates.
+ review_jsdoc_large:
+ if:
+ - {{ changes.ratio > 25}}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ No JSDoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to JavaScript classes, but is missing updates to JSDoc. Please double check for any necessary JSDoc updates.
+
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ # Sum all the line removed in the PR
+ deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
+ # Calculate the ratio of new code
+ ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}
+
+colors:
+ yellow: 'fbca04'
+
Require JSDoc for all new JavaScript classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing JSDoc
label.Enforce JSDoc for New JavaScript Classes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_jsdoc_new_class:
+ if:
+ - {{ is.javascript and is.new }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing JSDoc"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ JSDoc is required for all JavaScript classes. Please add JSDoc to all new classes in this PR.
+
+is:
+ javascript: {{ files | extensions | match(list=['js', 'ts']) | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Approve PRs that only contain changes to JSDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.📓 JSDoc Only label
Review JSDoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ #Assign PRs that only affect JSDocs to the technical writing team and add docs label
+ review_jsdoc:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/\/*\*[\s\S]*?\//) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓JSDoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
Warn PR authors when they change Ruby function or constructor input parameters without updating RDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review RDoc Input Parameters
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_rdoc_input:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/(\#.*\n.*)*def/) | nope }}
+ - {{ source.diff.files | match(attr='diff', regex=r/def.*\(.*\)/ | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR modifies method input parameters, but is missing RDoc changes. Please check to ensure no RDoc changes are necessary.
+
Require more extensive reviews for large Ruby changes that lack RDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.⚠️ Missing RDoc
LabelReview RDoc
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ #Require more extensive reviews for large Ruby changes that lack RDoc updates.
+ review_rdoc_large:
+ if:
+ - {{ changes.additions > 150}}
+ - {{ source.diff.files | matchDiffLines(regex=r/(\#.*\n.*)*def/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing RDoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to Ruby methods, but is missing updates to RDoc. Please double check for any necessary RDoc updates.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+
+
+colors:
+ yellow: 'fbca04'
+
Require RDoc for all new Ruby classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing RDoc
label.Enforce RDoc for New Ruby Classes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_rdoc_new_class:
+ if:
+ - {{ is.rb and is.new }}
+ - {{ source.diff.files | match(attr='diff', regex=r/(\#.*\n.*)*def/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing RDoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ RDoc is required for all Ruby classes. Please add documentation for this PR.
+
+is:
+ rb: {{ files | extensions | match(regex=r/rb/) | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Approve PRs that only contain changes to RDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
📓 RDoc Only
labelReview RDoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_rdoc:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/^[\s\t]*#.*/) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓RDoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [org/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
Automatically label PRs that are missing references to Shortcut resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Shortcut Link
labelLabel Missing Shortcut
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_shortcut:
+ if:
+ - {{not (has.shortcut.ticket_in_title or has.shortcut.ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Shortcut Link"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated Shortcut resource.
+
+has:
+ shortcut:
+ ticket_in_title: {{ pr.title | includes(regex=r/(\w+)\/sc-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/(app\.shortcut\.com)\/(\w+)\/story\/(\d+)\/(\w+)/) }}
+
+colors:
+ red: 'b60205'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Provide automatic links to Shortcut tasks that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Shortcut Task
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Configure these to match your organization.
+provider: jira
+
+# Change this to match the name of your Shortcut organization. This is used in tracker.shortcut.baseurl
+orgName: org
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_shortcut:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ shortcut:
+ baseurl: https://app.shortcut.com/[orgName]/story/
+ pattern: r/(\w+)\/sc-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Approve PRs that pass SonarCloud's quality gate.
Configuration Description
Conditions (all must be true):
Automation Actions:
Sonar: Clean Code
label to the PR.Aprove Sonar Clean Code
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+automations:
+ approve_sonar_clean_code:
+ if:
+ - {{ sonar.bugs.rating == 'A' }}
+ - {{ sonar.code_smells.rating == 'A' }}
+ - {{ sonar.vulnerabilities.rating == 'A' }}
+ - {{ sonar.security_hotspots.rating == 'A' }}
+ - {{ sonar.duplications == null or sonar.duplications == 0 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '✅ Sonar: Clean Code'
+ color: {{ colors.green }}
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR passes the SonarCloud quality gate check and as been automatically approved.
+
+sonar: {{ pr | extractSonarFindings }}
+
+colors:
+ green: '0e8a16'
+
Label the number of bugs, vulnerabilities, security hotspots, and code smells reported by SonarCloud.
Configuration Description
Conditions (all must be true):
extractSonarFindings
filter functionAutomation Actions:
Label SonarCloud Quality Reports
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in reports %}
+ label_sonar_{{ item.name }}:
+ if:
+ - {{ item.count > 0}}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.icon }} sonar:{{ item.name }}-{{ item.rating }}'
+ color: {{ colors.red if (item.rating == 'E' or item.rating == 'D') else (colors.orange if (item.rating == 'C' ) else colors.yellow) }}
+ {% endfor %}
+
+sonar: {{ pr | extractSonarFindings }}
+
+reports:
+ - name: vulnerabilities
+ count: {{ sonar.vulnerabilities.count }}
+ icon: 🔓
+ rating: {{ sonar.vulnerabilities.rating }}
+ - name: code smells
+ count: {{ sonar.code_smells.count }}
+ icon: ☣️
+ rating: {{ sonar.code_smells.rating }}
+ - name: security hotspots
+ count: {{ sonar.security_hotspots.count }}
+ icon: 🛡️
+ rating: {{ sonar.security_hotspots.rating }}
+ - name: bugs
+ count: {{ sonar.bugs.count }}
+ icon: 🪲
+ rating: {{ sonar.bugs.rating }}
+
+colors:
+ red: 'b60205'
+ orange: 'd93f0b'
+ yellow: 'fbca04'
+
Require additional reviews for Sonar security alerts. gitStream will remove this requirement if the alerts are resolved.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/security-team
team. Customize this to match your organization.Review Sonar Alerts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+automations:
+ review_sonar_alerts:
+ if:
+ - {{ sonar.code_smells.rating != 'A' or sonar.vulnerabilities.rating != 'A' or sonar.security_hotspots.rating != 'A'}}
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [my-organization/security-team]
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR requires additional review because it fails to meet SonarCloud clean code standards.
+
+sonar: {{ pr | extractSonarFindings }}
+
Request changes when Sonar reports an excessive level of duplicated code.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Sonar Duplications
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+automations:
+ review_sonar_duplications:
+ if:
+ - {{ sonar.duplications > 3 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'Sonar: {{ sonar.duplications}}% duplication'
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Sonar reports an excessive level of code duplication. Please consider refactoring your PR to reduce duplications.
+
+sonar: {{ pr | extractSonarFindings }}
+
+colors:
+ yellow: 'fbca04'
+
Approve changes that only affect Swimm documentation.
Configuration Description
Conditions (all must be true):
.swm
extension.Automation Actions:
swimm-docs-only
labelApprove Swimm Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_swimm_changes:
+ # Triggered for any changes to Swimm documentation
+ if:
+ - {{ branch.diff.files_metadata | match(attr='file', regex=r/\.swm\//) | every }}
+ # Apply a swimm-docs-only label, approve the PR and explain why in a comment.
+ run:
+ - action: add-label@v1
+ args:
+ label: 'swimm-docs-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is considered a safe change as it only affects Swimm Docs.
+ It has been automatically approved.
+
Special thanks to Omerr for providing this example.
Request changes if a PR that creates a new Terraform module which do not conform to the required directory structure.
Configuration Description
Conditions (all must be true):
/modules
directory.Automation Actions:
⚠️ Missing Terraform Components
Review New Module
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+{% set misslist = [] %}
+{% for pattern in terraform %}
+{% if (newfilesinpr | match(term=pattern) | nope) %}
+{% set misslist = misslist + [pattern+' '] %}
+{% endif %}
+{% endfor %}
+
+automations:
+ review_new_terraform_module:
+ if:
+ - {{misslist | match(regex=r/.*/) | some}}
+ - {{is.mainfile and is.mainfilenotinroot }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ New terraform modules must contain all required components before merging. Please update your PR with the required components and gitStream will automatically remove this comment once completed.
+
+ Here are the required components, {{misslist}} should be customized appropriately:
+ my_module/
+ ├── main.tf
+ ├── outputs.tf
+ ├── providers.tf
+ - action: add-label@v1
+ args:
+ label: '⚠️ Missing Terraform Components'
+ color: '#FFA500'
+
+resources:
+ module_directory: 'modules'
+terraform:
+ - main.tf
+ - outputs.tf
+ - providers.tf
+is:
+ mainfile: {{newfilesinpr | match(term = "main.tf") | some}}
+ mainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = "main.tf") | nope }}
+newfilesinpr:
+ {{ branch.diff.files_metadata | map(attr='new_file')}}
+
Request changes if a PR creates a new Terraform module that is missing a required prefix or keyword in the name.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Module Name
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Prefix Check Logic
+{% set prefixcheck = [] %}
+{% for pattern in terraform.prefixes %}
+{% if(newfilesinpr | match(term=module_location + pattern) | some) %}
+{% set prefixcheck = prefixcheck + [true]%}
+{% else %}
+{% set prefixcheck = prefixcheck + [false] %}
+{% endif %}
+{% endfor %}
+
+automations:
+ review_new_terraform_module:
+ if:
+ - {{is.mainfile and is.mainfilenotinroot}}
+ - {{module_name_checks.prefix or module_name_checks.keyword}}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ Terraform module names must contain a required prefix and keyword:
+ * Prefixes: {{ terraform.prefixes }}
+ * Keywords: {{ terraform.keywords }}
+
+module_name_checks:
+ prefix: {{prefixcheck | match(term='true') | nope}}
+ keyword: {{newfilesinpr | match(list=terraform.keywords) | nope}}
+
+module_location: infrastructure/modules/
+terraform:
+ prefixes: ['aws', 'gcp', 'azure']
+ keywords: ['db', 'networking', 'security']
+
+is:
+ mainfile: {{newfilesinpr | match(term = "main.tf") | some}}
+ mainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = "main.tf") | nope }}
+newfilesinpr:
+ {{ branch.diff.files_metadata | map(attr='new_file')}}
+
Ensure that all Terraform modules imported via a source URL specify a version.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_terraform_source_version:
+ # Check if New Content contains a source URL, the URL is not part of allow list and lacks version reference
+ if:
+ - {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\".*(http|https).*\"/) | some }}
+ - {{ source.diff.files | match(attr='new_content', list=allowlist) | nope }}
+ - {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\?ref=v.*/) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ You must reference a specific version when accessing Terraform module sources via URL, e.g. `?ref=v1.0.0`. Please update your Terraform files to follow this practice.
+
+allowlist:
+ - 'https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git'
+ - 'https://github.com/terraform-aws-modules/terraform-aws-vpc.git'
+ - 'https://github.com/terraform-aws-modules/terraform-aws-eks.git'
+
Automatically assign org/infrastructure
team for reviewing changes when PR contains Terraform file changes.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_terraform:
+ # Triggered for any changes to Terraform files
+ if:
+ - {{ files | match(regex=r/.*\.tf.*/) | some }}
+ # Assign infrastructure team as reviewer for change in Terraform files
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [org/infrastructure]
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR affects Terraform configurations and requires a review from the Infra team.
+
Label PRs that delete files.
Configuration Description
Conditions (all must be true):
Automation Actions:
deleted-files
label to the PR.Label Deleted Files
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Apply a label that indicates when a PR deletes files
+ # This uses the `has` custom expression found at the bottom of this file
+ label_deleted_files:
+ if:
+ - {{ has.deleted_files }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'deleted-files'
+ color: '#DF9C04'
+
+# This is used in the `label_deleted_files` automation
+has:
+ deleted_files: {{ source.diff.files | map(attr='new_file') | match(term='/dev/null') | some }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Label PRs that lack a reference to a project tracker issue (Jira, Azure Boards, Shortcut and Asana) in the PR title or description.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Project Tracker
Label Missing Project Tracker
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_project_tracker:
+ if:
+ - {{not (has[provider].ticket_in_title or has[provider].ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Project Tracker"
+ color: 'F6443B'
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated resource in your team's project tracker.
+
+has:
+ jira:
+ ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}
+ asana:
+ ticket_in_title: {{ pr.title | includes(regex=r/asana-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/app\.asana.\com\/(\d+)\/(\d+)\/(\d+)\/(\d+)\/(\d+)/) }}
+ azure:
+ ticket_in_title: {{ pr.title | includes(regex=r/(\w+)-(\w+)-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/(dev\.azure\.com|(\w+)\.visualstudio\.com)\/(\w+)\/(\w+)\/_workitems\/edit\/(\d+)/) }}
+ shortcut:
+ ticket_in_title: {{ pr.title | includes(regex=r/(\w+)\/sc-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/(app\.shortcut\.com)\/(\w+)\/story\/(\d+)\/(\w+)/) }}
+
+provider: jira
+
Apply a missing-tests
label to any PRs that don't update tests. gitStream will remove this label if the contributor adds a test change to the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-tests
label.gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Approve changes to Golang files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
.go
log
object.Automation Actions:
log-output-only
labelApprove Golang Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_golang_log_output:
+ # Triggered for Golang changes that only affect the console.log() method
+ if:
+ - {{ files | extensions | match(term='go') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*log\.Println/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve changes to Golang files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
.go
log
object.Automation Actions:
log-output-only
labelApprove Golang Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_golang_log_output:
+ # Triggered for Golang changes that only affect the console.log() method
+ if:
+ - {{ files | extensions | match(term='go') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*log\.Println/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Automatically request changes for Golang PRs that are missing tests.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Golang Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\/(?!.*\_test\.go$).*\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/.*\_test\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\/(?!.*\_test\.go$).*\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/.*\_test\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_golang_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Golang files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Automatically request changes for Golang PRs that are missing tests.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Golang Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\/(?!.*\_test\.go$).*\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/.*\_test\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\/(?!.*\_test\.go$).*\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/.*\_test\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_golang_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Golang files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for <title>
tags that don't comply with best practices.
Configuration Description
Conditions (all must be true):
<title>
tag that is less than 30 or greater than 90 characters.Automation Actions:
Enforce HTML Title Length Requirements
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ enforce_html_title_length:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/(<title>([\w\W]{1,29})<\/title>)|(<title>([\w\W]{61,})<\/title>)/) | some }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please ensure that all HTML titles are between 30 and 60 characters.
+
Automatically request changes for PRs HTML files that are missing image alt attributes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing alt label
labelEnforce Image Alt Attributes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ enforce_image_alt:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/<img src/) | some }}
+ - {{ source.diff.files | matchDiffLines(regex=r/<img src.*alt=/) | nope}}
+
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing alt label"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please ensure that all images in HTML files have an alt attribute. For example: <img alt="Alt Message">
+
+colors:
+ yellow: 'fbca04'
+
Automatically request changes when PRs contain HTML files that have more than one H1 heading.
Configuration Description
Conditions (all must be true):
Automation Actions:
Flag Duplicate H1
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ flag_duplicate_h1:
+ if:
+ - {{ duplicateH1 > 0 }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ This PR contains HTML files with multiple H1 tags. Please ensure that each HTML file has only one H1 tag.
+
+duplicateH1: {{ source.diff.files | filter(attr='new_content', regex=r/<h1>(.|\n)*<h1>/) | length }}
+
Request changes for HTML files that lack the canonical and robots tag.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Required Tag
label.Flag Missing HTML Tags
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ flag_missing_html_tags:
+ if:
+ - {{ is.html and is.new }}
+ - {{ source.diff.files | matchDiffLines(regex=r/rel="canonical"/) | nope }}
+ - {{ source.diff.files | matchDiffLines(regex=r/meta name="robots"/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Required Tag"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please ensure new HTML files contain canonical and robots meta tags.
+
+is:
+ html: {{ files | extensions | match(term='html') | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Flag the use of !important
in CSS files and automatically request changes.
Configuration Description
Conditions (all must be true):
!important
Automation Actions:
⚠️ Includes !important tag
Review Important Tags in CSS Files
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_javascript_formatting:
+ if:
+ - {{ files | extensions | match(term='css') | some }}
+ - {{ source.diff.files | matchDiffLines(regex=r/!important/) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '⚠️ Includes !important tag'
+ color: '{{ colors.orange }}'
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please remove the `!important` tag from your CSS.
+
+
+colors:
+ orange: 'd93f0b'
+
Request changes for HTML files that lack the canonical and robots tag.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Required Tag
label.Flag Missing HTML Tags
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ flag_missing_html_tags:
+ if:
+ - {{ is.html and is.new }}
+ - {{ source.diff.files | matchDiffLines(regex=r/rel="canonical"/) | nope }}
+ - {{ source.diff.files | matchDiffLines(regex=r/meta name="robots"/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Required Tag"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please ensure new HTML files contain canonical and robots meta tags.
+
+is:
+ html: {{ files | extensions | match(term='html') | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Automatically request changes when PRs contain HTML files that have more than one H1 heading.
Configuration Description
Conditions (all must be true):
Automation Actions:
Flag Duplicate H1
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ flag_duplicate_h1:
+ if:
+ - {{ duplicateH1 > 0 }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ This PR contains HTML files with multiple H1 tags. Please ensure that each HTML file has only one H1 tag.
+
+duplicateH1: {{ source.diff.files | filter(attr='new_content', regex=r/<h1>(.|\n)*<h1>/) | length }}
+
Automatically request changes for <title>
tags that don't comply with best practices.
Configuration Description
Conditions (all must be true):
<title>
tag that is less than 30 or greater than 90 characters.Automation Actions:
Enforce HTML Title Length Requirements
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ enforce_html_title_length:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/(<title>([\w\W]{1,29})<\/title>)|(<title>([\w\W]{61,})<\/title>)/) | some }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please ensure that all HTML titles are between 30 and 60 characters.
+
Automatically request changes for PRs HTML files that are missing image alt attributes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing alt label
labelEnforce Image Alt Attributes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ enforce_image_alt:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/<img src/) | some }}
+ - {{ source.diff.files | matchDiffLines(regex=r/<img src.*alt=/) | nope}}
+
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing alt label"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please ensure that all images in HTML files have an alt attribute. For example: <img alt="Alt Message">
+
+colors:
+ yellow: 'fbca04'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Flag the use of !important
in CSS files and automatically request changes.
Configuration Description
Conditions (all must be true):
!important
Automation Actions:
⚠️ Includes !important tag
Review Important Tags in CSS Files
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_javascript_formatting:
+ if:
+ - {{ files | extensions | match(term='css') | some }}
+ - {{ source.diff.files | matchDiffLines(regex=r/!important/) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '⚠️ Includes !important tag'
+ color: '{{ colors.orange }}'
+ - action: request-changes@v1
+ args:
+ comment: |
+ Please remove the `!important` tag from your CSS.
+
+
+colors:
+ orange: 'd93f0b'
+
Approve changes to Java files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Java Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_java_log_output:
+ # Triggered for Java changes that only affect the logger method
+ if:
+ - {{ files | extensions | match(term='java') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*logger\.(trace|fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve changes to Java files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Java Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_java_log_output:
+ # Triggered for Java changes that only affect the logger method
+ if:
+ - {{ files | extensions | match(term='java') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*logger\.(trace|fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Automatically request changes for Java PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Java Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*Test\.java$).*\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*Test\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*Test\.java$).*\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*Test\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_java_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Java files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for Java test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Java Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/test\/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/test\/) | length }}
+
+automations:
+ review_java_test_name:
+ if:
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^src\/test\/) | match(attr='new_file', regex=r/Test.java$/) | nope }}
+
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the Java test name conventions. A test file name needs to have the word Test at the end of class name. For example, if you are testing a class called Data then the test file name has to be DataTest.java.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Automatically request changes for Java test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Java Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/test\/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/test\/) | length }}
+
+automations:
+ review_java_test_name:
+ if:
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^src\/test\/) | match(attr='new_file', regex=r/Test.java$/) | nope }}
+
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the Java test name conventions. A test file name needs to have the word Test at the end of class name. For example, if you are testing a class called Data then the test file name has to be DataTest.java.
+
Automatically request changes for Java PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Java Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*Test\.java$).*\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*Test\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*Test\.java$).*\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*Test\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_java_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Java files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Approve PRs that only contain formatting changes to JavaScript or TypeScript files.
Configuration Description
Conditions (all must be true):
.js
or .ts
Automation Actions:
code-formatting
label.Approve JavaScript Formatting Change
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_javascript_formatting:
+ if:
+ - {{ files | extensions | match(list=['js', 'ts']) | every }}
+ - {{ source.diff.files | isFormattingChange }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: code-formatting
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR only contains formatting changes and has been approved.
+
Approve changes to JavaScript files that only affect lines of code that invoke the console.log() method.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove JavaScript Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_javascript_log_output:
+ # Triggered for JavaScript changes that only affect the console.log() method
+ if:
+ - {{ files | match(regex=r/\.js$|\.ts$/) | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^[+-].*console\.log/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve changes to JavaScript files that only affect lines of code that invoke the console.log() method.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove JavaScript Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_javascript_log_output:
+ # Triggered for JavaScript changes that only affect the console.log() method
+ if:
+ - {{ files | match(regex=r/\.js$|\.ts$/) | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^[+-].*console\.log/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve PRs that only contain formatting changes to JavaScript or TypeScript files.
Configuration Description
Conditions (all must be true):
.js
or .ts
Automation Actions:
code-formatting
label.Approve JavaScript Formatting Change
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_javascript_formatting:
+ if:
+ - {{ files | extensions | match(list=['js', 'ts']) | every }}
+ - {{ source.diff.files | isFormattingChange }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: code-formatting
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR only contains formatting changes and has been approved.
+
Request changes for JavaScript PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-tests
labelReview Missing JavaScript Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*\.test\.js$).*\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*\.test\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*\.test\.js$).*\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*\.test\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_javascript_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new JavaScript files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for JavaScript test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JavaScript Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | length }}
+
+automations:
+ review_javascript_test_name:
+ if:
+
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | match(attr='new_file', regex=r/.test.js$/) | nope }}
+
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the JavaScript test name conventions. A test file name needs to have the suffix .test after class name. For example, if you are testing a class file called Data.js then the test file name has to be data.test.js.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Automatically request changes for JavaScript test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JavaScript Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | length }}
+
+automations:
+ review_javascript_test_name:
+ if:
+
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | match(attr='new_file', regex=r/.test.js$/) | nope }}
+
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the JavaScript test name conventions. A test file name needs to have the suffix .test after class name. For example, if you are testing a class file called Data.js then the test file name has to be data.test.js.
+
Request changes for JavaScript PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-tests
labelReview Missing JavaScript Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*\.test\.js$).*\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*\.test\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!.*\.test\.js$).*\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\/.*\.test\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_javascript_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new JavaScript files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Approve PRs that only contain formatting changes to Python files.
Configuration Description
Conditions (all must be true):
.py
.Automation Actions:
code-formatting
label.Approve Python Formatting Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_python_formatting:
+ if:
+ - {{ files | extensions | match(list=['py']) | every }}
+ - {{ source.diff.files | isFormattingChange }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: code-formatting
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR only contains formatting changes and has been approved.
+
Approve changes to Python files that only affect lines of code that invoke a specified logging object.
Configuration Description
Conditions (all must be true):
logger
object. This should be customized to your environment.Automation Actions:
log-output-only
labelApprove Python Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_python_log_output:
+ # Triggered for python changes that only affect lines of code that invoke a logger object.
+ # Modify 'logger' to match your dev environment.
+ if:
+ - {{ files | match(regex=r/\.py$/) | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^[+-].*logger\.(trace|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve changes to Python files that only affect lines of code that invoke a specified logging object.
Configuration Description
Conditions (all must be true):
logger
object. This should be customized to your environment.Automation Actions:
log-output-only
labelApprove Python Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_python_log_output:
+ # Triggered for python changes that only affect lines of code that invoke a logger object.
+ # Modify 'logger' to match your dev environment.
+ if:
+ - {{ files | match(regex=r/\.py$/) | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^[+-].*logger\.(trace|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve PRs that only contain formatting changes to Python files.
Configuration Description
Conditions (all must be true):
.py
.Automation Actions:
code-formatting
label.Approve Python Formatting Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_python_formatting:
+ if:
+ - {{ files | extensions | match(list=['py']) | every }}
+ - {{ source.diff.files | isFormattingChange }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: code-formatting
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR only contains formatting changes and has been approved.
+
Automatically request changes for Python PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Python Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!test_.*\.py$).*\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\/test_.*\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!test_.*\.py$).*\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\/test_.*\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_python_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Python files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for Python test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Python Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | length }}
+
+automations:
+ review_python_test_name:
+ if:
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | match(attr='new_file', regex=r/test_.*\.py$/) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the Python test name conventions. A test file name needs to have the prefix test_ before class name. For example, if you are testing a class file called Data.py then the test file name has to be test_data.py.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Automatically request changes for Python PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Python Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!test_.*\.py$).*\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\/test_.*\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\/(?!test_.*\.py$).*\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\/test_.*\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_python_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Python files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for Python test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Python Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | length }}
+
+automations:
+ review_python_test_name:
+ if:
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | match(attr='new_file', regex=r/test_.*\.py$/) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the Python test name conventions. A test file name needs to have the prefix test_ before class name. For example, if you are testing a class file called Data.py then the test file name has to be test_data.py.
+
Approve changes to Ruby files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Ruby Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_ruby_log_output:
+ # Triggered for Ruby changes that only affect the logger method
+ if:
+ - {{ files | extensions | match(term='rb') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*logger\.(fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve changes to Ruby files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Ruby Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_ruby_log_output:
+ # Triggered for Ruby changes that only affect the logger method
+ if:
+ - {{ files | extensions | match(term='rb') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*logger\.(fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Automatically request changes for Ruby PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Ruby Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^app\/(?!.*\_spec\.rb$).*\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/spec\/.*\_spec\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^app\/(?!.*\_spec\.rb$).*\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/spec\/.*\_spec\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_ruby_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Ruby files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for Ruby test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Ruby Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | length }}
+
+automations:
+ review_ruby_test_name:
+ if:
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | match(attr='new_file', regex=r/_spec.rb$/) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the Ruby test name conventions. A test file name needs to have the suffix _spec after class name. For example, if you are testing a class file called data.rb then the test file name has to be data_spec.rb.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Automatically request changes for Ruby PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Ruby Tests
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+newFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^app\/(?!.*\_spec\.rb$).*\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/spec\/.*\_spec\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}
+
+newFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^app\/(?!.*\_spec\.rb$).*\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/spec\/.*\_spec\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}
+
+automations:
+ review_missing_ruby_tests:
+ if:
+ - {{ newFilesCount != newTestsCount }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Tests"
+ color: {{ colors.orange }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Some of your new Ruby files are missing corresponding tests. Please ensure that all new files have a corresponding test file.
+
+ **New Files**: {{ newFilesCount }}
+ {{ newFiles }}
+
+ **New Tests**: {{ newTestsCount }}
+ {{ newTests }}
+colors:
+ orange: 'd93f0b'
+
Automatically request changes for Ruby test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Ruby Test Name
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) }}
+newTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | length }}
+
+automations:
+ review_ruby_test_name:
+ if:
+ - {{ newTestsCount > 0}}
+ - {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | match(attr='new_file', regex=r/_spec.rb$/) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ The test file name does not follow the Ruby test name conventions. A test file name needs to have the suffix _spec after class name. For example, if you are testing a class file called data.rb then the test file name has to be data_spec.rb.
+
Approve changes to Rust files that only affect lines of code that invoke the logging marcos.
Configuration Description
Conditions (all must be true):
.rs
print
, println
or dbg
macros or use the log
crate macros.Automation Actions:
log-output-only
labelApprove Rust Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_rust_log_output:
+ # Triggered for Rust changes that only affect the logging macros
+ if:
+ - {{ files | extensions | match(term='rs') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*\b(println|print|dbg|error|warn|info|debug|trace)\b!/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
Approve changes to Rust files that only affect lines of code that invoke the logging marcos.
Configuration Description
Conditions (all must be true):
.rs
print
, println
or dbg
macros or use the log
crate macros.Automation Actions:
log-output-only
labelApprove Rust Log Output Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_rust_log_output:
+ # Triggered for Rust changes that only affect the logging macros
+ if:
+ - {{ files | extensions | match(term='rs') | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/^.*\b(println|print|dbg|error|warn|info|debug|trace)\b!/, ignoreWhiteSpaces=true) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'log-output-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR has been approved because it only contains changes to log output
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Post a comment that indicates what percentage of the PR contains new code.
Configuration Description
Conditions (all must be true):
Automation Actions:
changes
custom expression to post a comment that indicates what percentage of the PR is new code. Calculate the Percentage of New Code
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ percent_new_code:
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is {{ changes.ratio }}% new code.
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ # Sum all the line removed in the PR
+ deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
+ # Calculate the ratio of new code
+ ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Label all PRs with an estimated number of minutes it would take someone to review. gitStream will automatically update this label whenever a PR changes.
Configuration Description
Conditions (all must be true):
Automation Actions:
Provide Estimated Time to Review
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ 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 ) }}
+
+calc:
+ etr: {{ branch | estimatedReviewTime }}
+
+
+colors:
+ red: 'b60205'
+ yellow: 'fbca04'
+ green: '0e8a16'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
If the PR lacks an image file, or link to an image in the description, apply a no-screenshot
label and post a comment to request a screenshot. If the PR author updates the description, gitStream will remove the label.
Configuration Description
Conditions (all must be true):
Automation Actions:
no-screenshot
label.Request Screenshot
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ request_screenshot:
+ # Triggered for PRs that lack an image file or link to an image in the PR description
+ if:
+ - {{ not (has.screenshot_link or has.image_uploaded) }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'no-screenshot'
+ color: '#FF000A'
+ - action: add-comment@v1
+ args:
+ comment: |
+ Be a life saver 🛟 by adding a screenshot of the changes you made.
+
+has:
+ screenshot_link: {{ pr.description | includes(regex=r/!\[.*\]\(.*(jpg|svg|png|gif|psd).*\)/) }}
+ image_uploaded: {{ pr.description | includes(regex=r/<img.*src.*(jpg|svg|png|gif|psd).*>/) }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically enforce prefixes or keywords in PR branch names.
Configuration Description
Conditions (all must be true):
feature
fix
or stable
abc-
followed by a number.ignoreList
custom expression.Automation Actions:
❗ Incorrect Branch Name
Enforce Branch Naming Conventions
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ enforce_branch_name:
+ if:
+ - {{ not has.requiredBranchPrefix }}
+ - {{ not has.requiredBranchKeyword }}
+ - {{ not ignoreList }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "❗ Incorrect Branch Name"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ All PR branch names must be prefixed by feature, stable, or fix, and must contain a reference to a Jira ticket. E.g. 'feature-abc-1234'
+ Please move your changes to a new branch that meets these requirements and open a new PR.
+ - action: close@v1
+
+has:
+ requiredBranchPrefix: {{ branch.name | includes(regex=r/^(feature|stable|fix)/) }}
+ requiredBranchKeyword: {{ branch.name | includes(regex=r/abc+-\d+/) }}
+
+ignoreList: {{ branch.name | match(regex=r/^(development|staging)/) }}
+
Use gitStream to enforce branch naming conventions, review assignment, and other branch managment workflows.
Enforce Branch Naming Conventions - Automatically enforce prefixes or keywords in PR branch names.
Assign Reviewers Based on Target Branch - Automatically assign PR reviewers for target branches that include a specified keyword.
Automatically enforce prefixes or keywords in PR branch names.
Configuration Description
Conditions (all must be true):
feature
fix
or stable
abc-
followed by a number.ignoreList
custom expression.Automation Actions:
❗ Incorrect Branch Name
Enforce Branch Naming Conventions
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ enforce_branch_name:
+ if:
+ - {{ not has.requiredBranchPrefix }}
+ - {{ not has.requiredBranchKeyword }}
+ - {{ not ignoreList }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "❗ Incorrect Branch Name"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ All PR branch names must be prefixed by feature, stable, or fix, and must contain a reference to a Jira ticket. E.g. 'feature-abc-1234'
+ Please move your changes to a new branch that meets these requirements and open a new PR.
+ - action: close@v1
+
+has:
+ requiredBranchPrefix: {{ branch.name | includes(regex=r/^(feature|stable|fix)/) }}
+ requiredBranchKeyword: {{ branch.name | includes(regex=r/abc+-\d+/) }}
+
+ignoreList: {{ branch.name | match(regex=r/^(development|staging)/) }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically require copyright headers for all new source code files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Enforce Copyright Headers
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ enforce_copyright_header:
+ if:
+ - {{ source.diff.files | filter(attr='new_file', regex=r/src\//) | map(attr='original_file') | match(regex=r/^$/) | some }}
+ - {{ source.diff.files | matchDiffLines(regex=licence.licenceRegex) | nope }}
+
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ All new files in the '/src' directory must include the required copyright header at the top of the file. For example:
+ // Copyright (c) ORG and contributors. All rights reserved.
+ // Licensed under the MIT license. See LICENSE file in the project root for details.
+
+licence:
+ licenceRegex: r/(Copyright \(c\) )|(Licensed under the MIT license)/
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically enforce PR naming conventions; this example expects the format: <type>(<scope>): <short summary>
Configuration Description
Conditions (all must be true):
Automation Actions:
Enforce PR Semantic Title Names
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ enforce_pr_title:
+ if:
+ - {{ pr.title | match(regex=titlePolicy.titleRegex) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ All PRs must be titled according to our semantic naming policy: `<type>(<scope>): <short summary>`
+
+ Type must be one of the following:
+
+ * build
+ * ci
+ * docs
+ * feature
+ * fix
+
+ Scope must be one of the following:
+
+ * common
+ * core
+ * elements
+ * forms
+ * http
+titlePolicy:
+ titleRegex: r/\b(build|ci|docs|feature|fix)\b\s*\((common|core|elements|forms|http)\):\s*\w+.*/
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Post a comment that uses git blame and history to list the most relevant experts for all PRs. The comment will automatically update as additional commits are added to the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically enforce the use of required PR labels.
Configuration Description
Conditions (all must be true):
Automation Actions:
Missing Required Labels
label.Enforce Required Labels
manifest:
+ version: 1.0
+
+automations:
+ enforce_required_labels:
+ if:
+ - {{ pr.labels | match(list=['Core', 'Mobile', 'UI']) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: Please ensure that your PR is labeled with either 'Core', 'Mobile', or 'UI'. These labels help us to better track and manage your contribution. Thank you.
+
Use YAML to automate label management on your git repo with gitStream.
Automatically enforce the use of required PR labels.
Configuration Description
Conditions (all must be true):
Automation Actions:
Missing Required Labels
label.Enforce Required Labels
manifest:
+ version: 1.0
+
+automations:
+ enforce_required_labels:
+ if:
+ - {{ pr.labels | match(list=['Core', 'Mobile', 'UI']) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: Please ensure that your PR is labeled with either 'Core', 'Mobile', or 'UI'. These labels help us to better track and manage your contribution. Thank you.
+
Apply a label to all PRs that indicates what percentage of new lines of code modify one or more specified resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Changed Resources By Percent
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_resource_percent_{{ item.name }}:
+ if:
+ - {{ files | match(list=item.resources) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.additions | round }}% {{ item.name }}'
+ {% endfor %}
+
+resources:
+ core:
+ - src/app
+ - src/core
+ mobile:
+ - src/android
+ - src/ios
+ docs:
+ - docs/
+
+labels:
+ - name: Core
+ resources: {{ resources.core }}
+ additions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.core ) | map(attr='additions') | sum / total.additions * 100 }}
+ - name: Mobile
+ resources: {{ resources.mobile }}
+ additions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.mobile ) | map(attr='additions') | sum / total.additions * 100 }}
+ - name: Docs
+ resources: {{ resources.docs }}
+ additions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.docs ) | map(attr='additions') | sum / total.additions * 100 }}
+
+total:
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+
Automatically detect which programming languages are contained in PRs and automatically label the PRs appropriately.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label PRs by Language
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_{{ item.name }}_pr:
+ if:
+ - {{ files | match(regex=item.resources) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.name }}'
+ {% endfor %}
+
+labels:
+ - name: Java
+ resources: r/.java$/
+ - name: Rust
+ resources: r/.rs$/
+ - name: HTML
+ resources: r/.html$/
+ - name: JavaScript
+ resources: r/.js$/
+ - name: Python
+ resources: r/.py$/
+ - name: Golang
+ resources: r/.go$/
+ - name: Ruby
+ resources: r/.rb$/
+ - name: CSS
+ resources: r/.css/
+
Automatically label PRs when there are unresolved code review comments.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Unresolved Review Threads
Automatically suggest labels to apply to new PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Suggest Labels
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ suggest_labels:
+ if:
+ - {{ pr.labels | length == 0}}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ All PRs must contain labels that indicate which CI/CD systems must be run. PLease update your PR to include one of the following labels: `Build: Mobile`, `Build: UI`, `Build: All`, `Build: None`
+
+ Additionally, Here are some labels you can apply to this PR that may be helpful:
+ * Suggest Reviewer - Use this if you aren't sure who to assign as the reviewer.
+ * WIP - Indicate this is a work in progress that shouldn't be merged.
+
Automatically label PRs with the number of completed reviews that approve the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for help with these examples.
Automatically label PRs with the number of completed reviews that approve the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically label PRs to indicate what resources are being changed.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Modified Resources
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_resource_{{ item.name }}:
+ if:
+ -{{ branch.name | includes(regex=item.branch) or files | match(list=item.resources) }}
+ run:
+ - action: add-label@v1
+ args:
+ label: {{ item.name }}
+ {% endfor %}
+
+labels:
+ - name: Core
+ resources:
+ - src/app
+ branch: r/^core-/
+ - name: mobile
+ resources:
+ - src/android
+ - src/ios
+ branch: r/^mobile-/
+
Automatically detect which programming languages are contained in PRs and automatically label the PRs appropriately.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label PRs by Language
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_{{ item.name }}_pr:
+ if:
+ - {{ files | match(regex=item.resources) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.name }}'
+ {% endfor %}
+
+labels:
+ - name: Java
+ resources: r/.java$/
+ - name: Rust
+ resources: r/.rs$/
+ - name: HTML
+ resources: r/.html$/
+ - name: JavaScript
+ resources: r/.js$/
+ - name: Python
+ resources: r/.py$/
+ - name: Golang
+ resources: r/.go$/
+ - name: Ruby
+ resources: r/.rb$/
+ - name: CSS
+ resources: r/.css/
+
Apply a label to all PRs that indicates what percentage of new lines of code modify one or more specified resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Changed Resources By Percent
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_resource_percent_{{ item.name }}:
+ if:
+ - {{ files | match(list=item.resources) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.additions | round }}% {{ item.name }}'
+ {% endfor %}
+
+resources:
+ core:
+ - src/app
+ - src/core
+ mobile:
+ - src/android
+ - src/ios
+ docs:
+ - docs/
+
+labels:
+ - name: Core
+ resources: {{ resources.core }}
+ additions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.core ) | map(attr='additions') | sum / total.additions * 100 }}
+ - name: Mobile
+ resources: {{ resources.mobile }}
+ additions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.mobile ) | map(attr='additions') | sum / total.additions * 100 }}
+ - name: Docs
+ resources: {{ resources.docs }}
+ additions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.docs ) | map(attr='additions') | sum / total.additions * 100 }}
+
+total:
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+
Automatically label PRs when there are unresolved code review comments.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Unresolved Review Threads
Automatically suggest labels to apply to new PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Suggest Labels
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ suggest_labels:
+ if:
+ - {{ pr.labels | length == 0}}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ All PRs must contain labels that indicate which CI/CD systems must be run. PLease update your PR to include one of the following labels: `Build: Mobile`, `Build: UI`, `Build: All`, `Build: None`
+
+ Additionally, Here are some labels you can apply to this PR that may be helpful:
+ * Suggest Reviewer - Use this if you aren't sure who to assign as the reviewer.
+ * WIP - Indicate this is a work in progress that shouldn't be merged.
+
Post a PR comment that links the associated resource in your issue tracker, such as Jira, Azure Boards, Shortcut, Asana, and more.
Configuration Description
Conditions (all must be true):
Automation Actions:
Link Issue Tracker
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Configure these to match your organization.
+provider: jira
+orgName: org
+asanaProject: 1234
+azureProject: my_project
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ comment_issue_tracker:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ jira:
+ baseurl: https://[orgName].atlassian.net/browse/
+ pattern: r/\b[A-Za-z]+-\d+\b/
+ asana:
+ baseurl: https://app.asana.com/0/[asanaProject]/0/
+ pattern: r/asana-(\d+)/
+ azure:
+ baseurl: https://dev.azure.com/[orgName]/[azureProject]/_workitems/
+ pattern: r/(\w+)-(\w+)-(\d+)/
+ shortcut:
+ baseurl: https://app.shortcut.com/[orgName]/story/
+ pattern: r/(\w+)\/sc-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
When someone applies a suggest-reviewers
label to a PR, use codeExperts to assign recommended reviewers and post a comment with the explainCodeExperts
automation action.
Configuration Description
Conditions (all must be true):
Automation Actions:
codeExperts
to assign recommended reviewers.explainCodeExperts
to post a comment that lists the top code experts for the PR.Assign Code Experts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ assign_code_experts:
+ # Triggered when someone applies a suggest-reviewer label to a PR.
+ if:
+ - {{ pr.labels | match(term='suggest-reviewer') | some }}
+ # More info about code experts
+ # https://docs.gitstream.cm/filter-functions/#codeexperts
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | codeExperts(gt=10) }}
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically assign code reviews based on changed resources, code expertise, branch, and more.
When someone applies a suggest-reviewers
label to a PR, use codeExperts to assign recommended reviewers and post a comment with the explainCodeExperts
automation action.
Configuration Description
Conditions (all must be true):
Automation Actions:
codeExperts
to assign recommended reviewers.explainCodeExperts
to post a comment that lists the top code experts for the PR.Assign Code Experts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ assign_code_experts:
+ # Triggered when someone applies a suggest-reviewer label to a PR.
+ if:
+ - {{ pr.labels | match(term='suggest-reviewer') | some }}
+ # More info about code experts
+ # https://docs.gitstream.cm/filter-functions/#codeexperts
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | codeExperts(gt=10) }}
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
Automatically route and manage PRs based on the target or destination branch.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Target Branch
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ {% for item in branches %}
+ review_target_branch_{{ item.name }}:
+ if:
+ - {{ pr.target| match(regex=item.prefix) }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: {{ item.reviews }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ PRs to the {{ item.name }} branch require {{ item.reviews }} review(s).
+ - action: add-reviewers@v1
+ args:
+ reviewers: [{{ item.reviewers }}]
+ {% endfor %}
+
+branches:
+ - prefix: r/^release/
+ reviews: 4
+ name: Release
+ - prefix: r/^experimental-/
+ reviews: 1
+ name: Experimental
+
Review Source Branch
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ {% for item in branches %}
+ review_source_branch{{ item.name }}:
+ if:
+ - {{ branch.name | match(regex=item.prefix) }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: {{ item.reviews }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ Reviewers from the {{ item.name }} team have automatically been assigned to this PR.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [{{ item.reviewers }}]
+ {% endfor %}
+
+branches:
+ - prefix: r/^ABC/
+ reviewers: org/a-team
+ name: ABC
+ - prefix: r/^XYZ-/
+ reviewers: org/x-team
+ name: XYZ
+
Compare the changed files to a pre-defined list of files and directories in. If any files match, require a review from the team my-organization/security
.
Configuration Description
Conditions (all must be true):
sensitive_files
custom expression. Customize this list for your project.Automation Actions:
my-organization/security
to review the PR. Customize this value to match your organization.Review Sensitive Files
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Assign special teams to review sensitive files.
+ # This requires the `sensitive` custom expression found at the bottom of this file.
+ review_sensitive_files:
+ # For all files listed in the sensitive custom expression.
+ if:
+ - {{ files | match(list=sensitive_files) | some }}
+ run:
+ # Add reviewers from the dev-leads team, and require two approvals
+ # Modify `my-organization/security` to match your organization.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my-organization/security]
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR affects one or more sensitive files and requires review from the security team.
+
+# The `sensitive_file_review` automation requires this custom expression.
+# Modify this list to suit your security needs.
+sensitive_files:
+ - src/app/auth/
+ - src/app/routing/
+ - src/app/resources/
+
Automatically assign the PR author's team to review PRs.
Configuration Description
Conditions (all must be true):
teams
custom expression.Automation Actions:
Assign the Author's Team for Review
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in teams %}
+ review_team_{{ item.name }}:
+ if:
+ - {{ pr.author_teams | match(regex=item.regex) }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: [{{ item.team }}]
+ - action: add-comment@v1
+ args:
+ comment: |
+ This {{ item.name }} team has been automatically assigned to review this PR.
+ {% endfor %}
+
+teams:
+ - regex: r/ui-team/
+ name: UI Team
+ team: org/ui-team
+ - regex: r/mobile-team/
+ name: Mobile
+ team: org/mobile-team
+
Require the reviewer as a previous contributor with code expertise between set thresholds when PR contains Share Knowledge
label.
Configuration Description
Conditions (all must be true):
Share Knowledge
label has been applied to the PRAutomation Actions:
Knowledge Share
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ share_knowledge:
+ if:
+ - {{ pr.labels | match(term='Share Knowledge') | some }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | codeExperts(gt=30, lt=60) | random }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ gitStream has assigned a reviewer to increase knowledge sharing on this PR.
+
Automatically notify code reviewers based on a resource watchlist.
Configuration Description
Conditions (all must be true):
watchers
custom expression.Automation Actions:
Notify Watcher
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+## change orgName to match your git organization name.
+orgName: company
+
+automations:
+ {% for item in watchers %}
+ notify_watcher_{{ item.owner if item.owner else item.team }}:
+ if:
+ - {{ (files | match(list=item.files) | some) or (source.diff.files | match(attr="diff", list=item.diffs) | some) }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ @{{ item.owner if item.owner else (["{{ orgName }}/", item.team] | join) }} - this PR has changes you're watching
+
+ {% if files | match(list=item.files) | some -%}
+ files:
+ {%- for file in files | filter(list=item.files) %}
+ - {{ file }}
+ {%- endfor -%}
+ {%- endif %}
+
+ {% if source.diff.files | match(attr="diff", list=item.diffs) | some -%}
+ diffs:
+ {%- for diff in item.diffs -%}
+ {%- if source.diff.files | match(attr="diff", list=diff) | some %}
+ - {{ diff }}
+ {%- for file in source.diff.files | filter(attr="diff", list=diff) | map(attr="new_file") %}
+ - {{ file }}
+ {%- endfor -%}
+ {%- endif -%}
+ {%- endfor -%}
+ {%- endif %}
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ item.owner }}
+ team_reviewers: {{ item.team }}
+ {% endfor %}
+
+
+
+watchers:
+ - owner: juliaspencer
+ files:
+ - src/auth
+ - team: release
+ files:
+ - package.json
+ - yarn.lock
+
Automatically notify code reviewers based on a resource watchlist.
Configuration Description
Conditions (all must be true):
watchers
custom expression.Automation Actions:
Notify Watcher
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+## change orgName to match your git organization name.
+orgName: company
+
+automations:
+ {% for item in watchers %}
+ notify_watcher_{{ item.owner if item.owner else item.team }}:
+ if:
+ - {{ (files | match(list=item.files) | some) or (source.diff.files | match(attr="diff", list=item.diffs) | some) }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ @{{ item.owner if item.owner else (["{{ orgName }}/", item.team] | join) }} - this PR has changes you're watching
+
+ {% if files | match(list=item.files) | some -%}
+ files:
+ {%- for file in files | filter(list=item.files) %}
+ - {{ file }}
+ {%- endfor -%}
+ {%- endif %}
+
+ {% if source.diff.files | match(attr="diff", list=item.diffs) | some -%}
+ diffs:
+ {%- for diff in item.diffs -%}
+ {%- if source.diff.files | match(attr="diff", list=diff) | some %}
+ - {{ diff }}
+ {%- for file in source.diff.files | filter(attr="diff", list=diff) | map(attr="new_file") %}
+ - {{ file }}
+ {%- endfor -%}
+ {%- endif -%}
+ {%- endfor -%}
+ {%- endif %}
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ item.owner }}
+ team_reviewers: {{ item.team }}
+ {% endfor %}
+
+
+
+watchers:
+ - owner: juliaspencer
+ files:
+ - src/auth
+ - team: release
+ files:
+ - package.json
+ - yarn.lock
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically route and manage PRs based on the target or destination branch.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Target Branch
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ {% for item in branches %}
+ review_target_branch_{{ item.name }}:
+ if:
+ - {{ pr.target| match(regex=item.prefix) }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: {{ item.reviews }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ PRs to the {{ item.name }} branch require {{ item.reviews }} review(s).
+ - action: add-reviewers@v1
+ args:
+ reviewers: [{{ item.reviewers }}]
+ {% endfor %}
+
+branches:
+ - prefix: r/^release/
+ reviews: 4
+ name: Release
+ - prefix: r/^experimental-/
+ reviews: 1
+ name: Experimental
+
Review Source Branch
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ {% for item in branches %}
+ review_source_branch{{ item.name }}:
+ if:
+ - {{ branch.name | match(regex=item.prefix) }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: {{ item.reviews }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ Reviewers from the {{ item.name }} team have automatically been assigned to this PR.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [{{ item.reviewers }}]
+ {% endfor %}
+
+branches:
+ - prefix: r/^ABC/
+ reviewers: org/a-team
+ name: ABC
+ - prefix: r/^XYZ-/
+ reviewers: org/x-team
+ name: XYZ
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Compare the changed files to a pre-defined list of files and directories in. If any files match, require a review from the team my-organization/security
.
Configuration Description
Conditions (all must be true):
sensitive_files
custom expression. Customize this list for your project.Automation Actions:
my-organization/security
to review the PR. Customize this value to match your organization.Review Sensitive Files
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Assign special teams to review sensitive files.
+ # This requires the `sensitive` custom expression found at the bottom of this file.
+ review_sensitive_files:
+ # For all files listed in the sensitive custom expression.
+ if:
+ - {{ files | match(list=sensitive_files) | some }}
+ run:
+ # Add reviewers from the dev-leads team, and require two approvals
+ # Modify `my-organization/security` to match your organization.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my-organization/security]
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR affects one or more sensitive files and requires review from the security team.
+
+# The `sensitive_file_review` automation requires this custom expression.
+# Modify this list to suit your security needs.
+sensitive_files:
+ - src/app/auth/
+ - src/app/routing/
+ - src/app/resources/
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Automatically assign the PR author's team to review PRs.
Configuration Description
Conditions (all must be true):
teams
custom expression.Automation Actions:
Assign the Author's Team for Review
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in teams %}
+ review_team_{{ item.name }}:
+ if:
+ - {{ pr.author_teams | match(regex=item.regex) }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: [{{ item.team }}]
+ - action: add-comment@v1
+ args:
+ comment: |
+ This {{ item.name }} team has been automatically assigned to review this PR.
+ {% endfor %}
+
+teams:
+ - regex: r/ui-team/
+ name: UI Team
+ team: org/ui-team
+ - regex: r/mobile-team/
+ name: Mobile
+ team: org/mobile-team
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Require the reviewer as a previous contributor with code expertise between set thresholds when PR contains Share Knowledge
label.
Configuration Description
Conditions (all must be true):
Share Knowledge
label has been applied to the PRAutomation Actions:
Knowledge Share
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ share_knowledge:
+ if:
+ - {{ pr.labels | match(term='Share Knowledge') | some }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | codeExperts(gt=30, lt=60) | random }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ gitStream has assigned a reviewer to increase knowledge sharing on this PR.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Request changes if a PR that meets specified criteria lacks an update to the project's changelog.
Configuration Description
Conditions (All must be true):
feature
Automation Actions:
⚠️ Missing Changelog
Review Changelog
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ # Request changes for new features that lack changelog updates.
+ review_changelog:
+ if:
+ - {{ branch.name | includes(term="feature") }}
+ - {{ files | match(regex=r/^docs\/changelog\.md$/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Changelog"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ All new features require an update to the changelog. Please modify your PR to include any relevant changelog updates.
+
+colors:
+ yellow: 'fbca04'
+
Special thanks to Boemo W Mmopelwa for providing this example.
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Request changes for a PR that contains a TODO statement.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review TODO Comments
Post a comment that summarizes which programming languages are contained in PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Summarize Language Changes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+
+automations:
+ summarize_language_changes:
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment:
+ <h3>Summary of Changes by Language</h3>
+ <table>
+ <tr>
+ <td>Language</td>
+ <td>Language Change Percentage</td>
+ </tr>
+ <tr>
+ <td>Java</td>
+ <td>{{ total.java | round }}%</td>
+ </tr>
+ <tr>
+ <td>JavaScript</td>
+ <td>{{ total.javascript | round }}%</td>
+ </tr>
+ <td>Rust</td>
+ <td>{{ total.rust | round }}%</td>
+ </tr>
+ <tr>
+ <td>Ruby</td>
+ <td>{{ total.ruby | round }}%</td>
+ </tr>
+ <td>HTML</td>
+ <td>{{ total.html | round }}%</td>
+ </tr>
+ <td>CSS</td>
+ <td>{{ total.css | round }}%</td>
+ </tr>
+ <tr>
+ <td>Golang</td>
+ <td>{{ total.golang | round }}%</td>
+ </tr>
+ <tr>
+ <td>Python</td>
+ <td>{{ total.python | round }}%</td>
+ </tr>
+ </table>
+
+total:
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ java: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.java$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ javascript: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.js$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ rust: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.rs$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ ruby: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.rb$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ html: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.html$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ css: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.css$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ golang: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.go$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+ python: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.py$/ ) | map(attr='additions') | sum / total.additions * 100 }}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
This header is useful to add to the top of any configuration files you create for your organization. This will help others who want to make improvements to your configurations in the future.
CM File Header
# -*- 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/
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
This automation demonstrates all of GitHub's default label colors, implemented as a colors
custom expression. This is meant to help improve other automations rather than being used on its own.
Colors Custom Expression
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# This automation demonstrates all of GitHub's default label colors.
+# This is meant to be used as a reference, not as an automation in your repo.
+automations:
+ label_colors:
+ if:
+ - true
+ run:
+ - action: add-label@v1
+ args:
+ label: "Test Label"
+ color: {{ colors.green }}
+
+# These are all of the colors in GitHub's default label color palette.
+colors:
+ red: 'b60205'
+ orange: 'd93f0b'
+ yellow: 'fbca04'
+ green: '0e8a16'
+ teal: '006b75'
+ blue: '1d76db'
+ dark-blue: '0052cc'
+ purple: '5319e7'
+ light-red: 'e99695'
+ light-orange: 'f9d0c4'
+ light-yellow: 'fef2c0'
+ light-green: 'c2e0c6'
+ light-teal: 'bfdadc'
+ light-blue: 'c5def5'
+ light-dark-blue: 'bfd4f2'
+ light-purple: 'd4c5f9'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Post a welcome message when someone makes their first PR to a repo, and provide context to help them know what's next.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/mentors
team to review the PR. Customize this to match your organization.new-contributor
label to the PR.Welcome Newcomer
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ # Help newcomers find mentors to guide them.
+ welcome_newcomer:
+ # If the PR author made their first contirbution on the current day
+ if:
+ - {{ repo.author_age < 1 and repo.age > 0 }}
+ # 1. Add reviewers from the team `my_organization/mentors`. Replace this string to match your organization
+ # 2. Apply a new-contributor label.
+ # 3 Post a comment that explains the next steps.
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my_organization/mentors]
+ - action: add-label@v1
+ args:
+ label: 'new-contributor'
+ color: '#FBBD10'
+ - action : add-comment@v1
+ args:
+ comment: |
+ Hello {{ pr.author }} 👋 Thanks for making your first PR, and welcome to our project!
+ Our mentor team has automatically been assigned to review this PR and guide you through the process.
+ Please reach out to that team if you have questions about the next steps.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Continuous Merge automation files have a .cm
extension. In a repository, gitStream loads and parse the .cm
directory, which can have multiple automation files, each of which is evaluated independently.
You can edit the .cm
files and add your own checks and rules. Check out the Automation examples.
There are two types of automation rules: repository level rules and organization level rules.
Repository level rules are set by creating a special .cm
directory in the repository root. Automation rules are specified in files in this directory, which can have any name but must end with .cm
.
Organization level rules are defined by creating a special repository named cm
in the organization or group. In this repository, you can add CM automation files, which will apply to all the repositories that gitStream app is connected.
When organization level rules are defines, repository level automation shall take precedence and override organization automation when having the same identifier.
An automation identifier is a composition of the CM file name and the automation name. For example when safe_changes
is defined in gitstream.cm
then the automation identifier shall be gitstream/safe_changes
Tip
You can exclude certain repositories per automation file using the config.ignore_repositories
Repository automation rules are set by creating a special .cm
directory in your repository root. Automation rules are specified in files in this directory, these files can have any name but must end with .cm
. By default, you start with a single automation file .cm/gitstream.cm
.
Every file is parsed independently, and the parsing results are combined and executed.
Specifically:
.cm
filesconfig
section is defined per .cm
file (except config.admin
)When configured correctly, your repository directory structure should look like that (for GitHub):
.
+├─ .cm/
+│ └─ *.cm
+├─ .github/
+│ └─ workflows/
+│ └─ gitstream.yml
+
Note
The .cm/gitstream.cm
is special, as it allows for repository level configuration such as config.admin
.
Organization automation rules are defined by creating a special repository cm
in your organization or group. In this repository, you can add CM automation files, which will apply to all the repositories that gitStream app is connected.
When configured correctly, the cm
repository directory structure should look like that (for GitHub):
For each PR the following automation rules are applied:
When organization level rules are defined, then the CI/CD will be executed on the cm
repository on behalf of the PR repository.
By utilizing the following techniques, you can effectively combine and manage global and repository rules to customize the behavior of your automations to fit the specific requirements of your repositories:
cm
repository and are applied to all repositories that are connected to gitStream.cm
repository and add a list of the unwanted repositories under the config.ignore_repositories
property in the CM file.The following sections are used in .cm
file to describe the desired automations:
manifest
The first section in a gitstream.cm
file is the manifest
.
The only field required is version
.
Key | Required | Type | Description |
---|---|---|---|
manifest | Y | Map | The manifest section root |
manifest.version | Y | String | Specify the .cm spec version: 0.1, 1.0 |
The manifest version field is used to parse the .cm
file, in the future if breaking changes are introduced to the parser then older automation will be still supported.
config
The config
section is optional in the .cm
file and is used to specify configuration for the way gitStream works.
Key | Type | Default | Scope | Description |
---|---|---|---|---|
config | Map | - | per .cm file | The config section, applies for the automations defined in the current file |
config.admin.users | [String] | [] | gitstream.cm | Admin user list (use the Git provider user names) |
config.ignore_files | [String] | [] | per .cm file | Exclude specific files |
config.ignore_repositories | [String] | [] | per .cm file | Exclude specific repositories |
config.user_mapping | [String: String] | [] | per .cm file | Key value list of Git user detailes and Git provider account names |
config.admin.users
When specified in gitstream.cm
the config.admin.users
allows adding admin rights, when a PR changes the *.cm
files only, if the user is listed in config.admin.users
the PR will be then approved by gitStream. For example, setting popeye
as admin:
This configuration is valid only when used in .cm/gitstream.cm
, when defined in other .cm
files this configuration is ignored.
When you add a user to config.admin.users
in your organization's cm
repository, they are granted administrative privileges to CM changes across every repository in the organization. gitStream evaluates CM rules in the individual repository and your organization's cm
repository to determine admin users.
config.ignore_files
The config.ignore_files
supports glob pattern matching that contains a list of files to ignore.
Common usage, since some files such as lock files are intentionally not a required part of a review, they would not want to them to be counted in the estimated review time. In such cases, you can add config.ignore_files
to the relevant CM file, for example:
config:
+ ignore_files:
+ - 'yarn.lock'
+ - 'package-lock.json'
+ - 'openapi.json'
+ - 'ui/src/**/*Model.d.ts'
+
config.ignore_repositories
The config.ignore_repositories
contains a list of repositories to ignore, for example:
For the listed repositories, the automation defined in the CM file shall not apply.
config.user_mapping
Accepts list of key value strings.
For example, when using rankByGitBlame
or explainRankByGitBlame
Git users are mapped to their matching Git provider accounts based on the Git details. The automatic mapping can sometimes result with the wrong account or fail to find a proper mapping, in these cases you can configure the config.user_mapping
. This allows you to map confusing Git user into their specific accounts and dump some irrelevant accounts:
config:
+ user_mapping:
+ - 'Popeye Man <popeye@invalid.com>': 'popeye-the-salyor-man' # (1)
+ - 'Popeye Man <popeye2@invalid.com>': 'popeye-the-salyor-man' # (2)
+ - 'olive <olive@invalid.com>': null # (3)
+
null
removes this Git user from the suggested resultsWhen using rankByGitBlame
to assign reviewers automatically with add-reviewers@v1
then mapping users to null
is a way to prevent the automatic mapping in certain cases, like in your example contributors that are not longer part of the team.
On the other hand, when using explainRankByGitBlame
with add-comment@v1
it still shows these users details in the PR comment suggestion as this info might be valuable by itself.
- action: add-reviewers@v1
+ args: # (1)
+ reviewers: {{ repo | rankByGitBlame(gt=25) }}
+
+- action: add-comment@v1
+ args: # (2)
+ comment: |
+ {{ repo | explainRankByGitBlame(gt=25) }}
+
rankByGitBlame
will drop null
usersexplainRankByGitBlame
will NOT drop null
usersautomations
The automations
section defines the automations and their conditions.
automations:
+ mark_small_pr:
+ if:
+ - {{ checks.size.is.xsmall }}
+ run:
+ - action: add-label@v1
+ args:
+ label: xsmall
+
Each automation includes its name, and few fields: if
and run
.
Key | Required | Type | Description |
---|---|---|---|
automations | Y | Map | The automations section root |
automations.NAME | Y | Map | User defined name of the automation, can be any string |
automations.NAME.if | Y | Map | List of conditions with AND relationship |
automations.NAME.run | Y | Map | Actions to run if all conditions are met, invoked one by one |
The if
field includes the list of conditions. The conditions are checked when a pull request is opened or changed, if all the conditions pass, the automation is executed.
The run
field includes the automation to execute. It includes the following fields:
Key | Required | Type | Description |
---|---|---|---|
action | Y | String | The action pointer |
engine | N | String | The action engine, default is gitstream |
args | N | List | The action inputs list |
For gitstream
engine, the action is specified by: name@version
gitStream supported actions, see actions.
You can define an accessory section, e.g. checks
, that defines common conditions, and reuse.
size:
+ is:
+ small: {{ branch.diff.size < 20 }}
+ medium: {{ branch.diff.size >= 20 and branch.diff.size < 100 }}
+ large: {{ branch.diff.size >= 100 }}
+
+automations:
+ approve_small:
+ if:
+ - {{ size.is.small }}
+ run:
+ - action: approve@v1
+ mark_small_medium:
+ if:
+ # Check that the PR is either small or medium size
+ - {{ size.is.small or size.is.medium }}
+ # AND its less than 5 minutes review (estimated)
+ - {{ branch | estimatedReviewTime <= 5 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'good-size'
+
Context variable are the inputs for the automation conditions or checks.
Legend
The icons indicate the availability status of each action.
gitStream includes a collection of variables called contexts.
The following structures are used in the context objects:
Partial example of a context object for a PR that changed few lines in a README.md
file:
{
+ "branch": {
+ "name": "new-feature-branch",
+ "base": "main",
+ "diff": {
+ "size": 50,
+ "files_metadata": [
+ {
+ "original_file": "README.md",
+ "new_file": "README.md",
+ "deletions": 0,
+ "additions": 2
+ }
+ ]
+ },
+ "num_of_commits": 1
+ },
+ "source": {
+ "diff": {
+ "files": [
+ {
+ "original_file": "README.md",
+ "new_file": "README.md",
+ "diff": "@@ -10,3 +10,5 @@ This project \n+\n+## Intro",
+ "original_content": "This project \n",
+ "new_content": "This project \n\n## Intro"
+ }
+ ]
+ }
+ },
+ "repo": {
+ "contributors": {
+ "popeye": "46",
+ "olive": "6"
+ },
+ "owner": "acme"
+ },
+ "files": [
+ "README.md"
+ ]
+}
+
branch
The branch
context contains info regarding the branch changes compared to the base branch.
Note
compared to the source
context does not include actual source code.
Values | Type | Description |
---|---|---|
branch | Map | Includes the info related to the current branch |
branch.author | String | The branch author (the user that did first commit in the branch). The formatted like author in git-log , e.g. Popeye <popeye@acme.com> |
branch.author_name | String | The branch author name |
branch.author_email | String | The branch author email |
branch.base | String | The main branch, main |
branch.commits.messages | [String] | A list with all the commit messages in this branch |
branch.diff.size | Integer | The sum of line changed: additions, edits and deletions |
branch.diff.files_metadata | FileMetadata | List of changed files including their relative path |
branch.name | String | The current branch, feature-123-branch |
branch.num_of_commits | Integer | The number of commits in the branch |
The branch context doesn't include any source code, but only related metadata.
Example for using branch.name
and branch.author
to automatically approve and merge version bumps.
automations:
+ dependabot:
+ if:
+ - {{ branch.name | includes(term="dependabot") }}
+ - {{ branch.author | includes(term="dependabot") }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: "approved-dependabot"
+ - action: merge@v1
+ args:
+ wait_for_all_checks: true
+ squash_on_merge: true
+
Tip
The files
context doesn't include deleted file, to identify both modified and deleted files use the branch.diff.files_metadata
, for example:
env
The env
context allows the user to pass data from the repo that is unavailable in the other context variables. Thus, the structure of the variable is not fixed and depends on user configuration.
To configure the env
variable, add the env
field to gitstream's workflow job configurations on .github/workflows/gitstream.yml
, under the Evaluate Rules
step. For more information, visit GitHub's guide for Using secrets in GitHub Actions The env
field
...
+ name: gitStream workflow automation
+ steps:
+ - name: Evaluate Rules
+ env:
+ SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
+...
+
To use the context variable, access to the env
variable's fields as configured in gitstream.yml
automations:
+ send_slack:
+ if:
+ - true
+ run:
+ - action: send-slack-message@v1
+ args:
+ message: "Hello world :tada:."
+ webhook_url: "{{ slack_webhook }}"
+
+slack_webhook: {{ env.SLACK_WEBHOOK }}
+
files
The files
context includes the list of changed files in the branch compared to the main branch.
Values | Type | Description |
---|---|---|
files | [String] | List of all changed files with their full path |
For example, a typical files
context can look like this:
Example for checking if certain changes are made:
automations:
+ ui_review:
+ if:
+ - {{ files | match(list=ui_templates_files) | some }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: [GitHubUser1, GitHubUser2]
+
+ui_templates_files:
+ - resources/app/ui_template.yml
+ - resources/app/role_template.yml
+ - resources/app/account_template.yml
+
pr
The pr
context includes metadata related to the pull request.
Values | Type | Description |
---|---|---|
pr | Map | Includes the info related to the PR |
pr.approvals | [String] | A list of the of reviewers that approved the PR |
pr.author | String | The PR author name |
pr.author_teams | String | The teams which the PR author is member of |
pr.author_is_org_member | Bool | true if the PR author is a member of the organization where gitStream is installed |
pr.checks | [Check ] | List of checks, names and status |
pr.comments | [Comment ] | List of PR comments objects |
pr.conflicted_files_count | Integer | The number files in the PR with conflicts |
pr.conversations | [Conversation ] | List of PR conversation objects, usually when reviewer have comments about the source code |
pr.created_at | String | The date and time the PR was created |
pr.draft | Bool | true when the PR is marked as Draft/WIP |
pr.description | String | The PR description text |
pr.labels | [String] | The labels that are attached to the PR |
pr.number | Integer | The PR or MR Id number |
pr.provider | String | The Git cloud provider name, e.g. GitHub , GitLab etc. |
pr.reviewers | [String] | The list of reviewers set for this PR |
pr.status | String | The PR status: open , closed and merged |
pr.target | String | The branch the PR is intended merged into |
pr.title | String | The PR title |
pr.requested_changes | [String] | List of users that requested changes |
pr.reviews | [Review ] | List of PR reviews, relevant in GitHub |
pr.unresolved_threads | Integer | The number of open review comments in the PR |
pr.updated_at | String | The date and time the PR was last updated |
Example for checking the PR title includes a Jira ticket:
automations:
+ check_jira_ticket:
+ if:
+ - {{ not has.jira_ticket }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "missing-ticket"
+ color: 'F6443B'
+
+has:
+ jira_ticket: {{ pr.title | includes(regex=r/^\[?\w{3,4}-\d{1,6}\]?(\s|-|_).{20,}$/) }}
+
repo
The repo
context includes metadata related to the repo.
Values | Type | Description |
---|---|---|
repo | Map | Includes the info related to the current repo |
repo.age | Integer | Number of days since first commit (of any user) |
repo.author_age | Integer | number of days since first commit to this repo |
repo.blame | GitBlame | The percentage each user's lines in a file, the list includes all changed files in the branch. The list is sorted by the ratio field |
repo.contributors | Contributor | List of contributors in the repo |
repo.git_activity | GitActivity | Per file and user, the number of lines changed every week for the last 52 weeks |
repo.name | String | Repository name |
repo.owner | String | Repository owner account name |
repo.visibility | String | The visibility of the source branch repo. Value is one of: private , internal , or public |
source
The source
context includes a list of FileDiff
objects that can be used to get insights based on code changes. The changes compared to the latest main branch.
Values | Type | Description |
---|---|---|
source.diff.files | FileDiff | List of changed files with their code changes |
The source context include all code changes, it is not safe to share it with unknown services.
Check
structure{
+ "name": String, # The check name
+ "status": String, # The check status: `queued`, `in_progress`, `completed`
+ "conclusion": String, # The check conclusion: `action_required`, `cancelled`, `failure` `neutral`, `success`, `skipped`, `stale`, `timed_out`
+}
+
Comment
structure{
+ "commenter": String, # The user that add the comment
+ "content": String, # The comment body
+ "created_at": String, # The time on which the comment was created
+ "updated_at": String, # The time on which the comment was last updated
+}
+
Conversation
structure{
+ "commenter": String, # The user that add the comment
+ "content": String, # The comment body
+ "created_at": String, # The time on which the comment was created
+ "updated_at": String, # The time on which the comment was updated
+ "start_line": Integer, # The first line marked for this comment
+ "end_line": Integer, # The last line marked for this comment
+ "is_resolved": Boolean # `true` when marked as resolved
+}
+
Contributor
structureThe repo.contributors
mapping includes a list of Contributor
, where the user name is used as dynamic key:
FileDiff
structureThe source.diff.files
mapping includes a list of FileDiff
:
{
+ "diff": String, # The content in diff format `+` for additions, `-` for deletions
+ "new_content": String, # The new content in this branch
+ "new_file": String, # The name of the file after the changes, including its path
+ "original_content": String, # The content as is in the `main` branch
+ "original_file": String, # The name of the file before the changes, including its path
+}
+
FileMetadata
structureThe branch.diff.files_metadata
mapping includes a list of FileMetadata
:
{
+ "additions": Integer, # The number of lines edited or added to the file
+ "deletions": Integer, # The number of lines removed from the file
+ "file": String, # The name of the file before the changes, including its path
+}
+
For example, sum additions in javascript code files:
{{ branch.diff.files_metadata | filter(attr='new_file', regex=r/\.js$|\.ts$/) | map(attr='additions') | sum }}
+
GitActivity
structureThis structure include per changed file, for every user, the number of lines changed every week for the last 52 weeks.
{
+ FILE_NAME: # The file name and path
+ {
+ # The git user identifier (String)
+ GIT_USER: {
+ "week_INDEX": Integer # Number of lines changed that week
+ # ... for the last 52 weeks
+ }
+ }
+}
+
For example:
{
+ "src/utils/service.js": {
+ "popeye <popeye@acme.com>": {
+ "week_1": 20,
+ "week_2": 15,
+ "week_10": 250
+ },
+ "olive <olive@acme.com>": {
+ "week_1": 3,
+ "week_3": 50,
+ "week_52": 250
+ }
+ },
+ "README.md": {
+ "popeye <popeye@acme.com>": {
+ "week_2": 15,
+ "week_3": 10
+ }
+ }
+}
+
GitBlame
structureFor each file, a list of user's blame ratio.
{
+ FILE_NAME: # The file name and path
+ {
+ # The git user identifier (String)
+ GIT_USER: Integer, # Precentage 0-100, ratio of user's lines / total lines in file
+ }
+}
+
For example:
{
+ "src/utils/service.js": {
+ "popeye <popeye@acme.com>": 78,
+ "olive <olive@acme.com>": 22,
+ },
+ "README.md": {
+ "popeye <popeye@acme.com>": 13,
+ "olive <olive@acme.com>": 22,
+ "brutus <brutus@acme.com>": 65,
+ }
+}
+
Review
structure{
+ "commenter": String, # The user that add the comment
+ "content": String, # The comment body
+ "created_at": String, # The time on which the comment was created
+ "state": String, # Either `approved`, `changes_requested`, `commented`, `pending`, `submitted`
+ "conversations": [Conversation], # Conversations that are relvant to this Review feedback
+}
+
Language | +Language Change Percentage | +
Java | +{{ total.java | round }}% | +
JavaScript | +{{ total.javascript | round }}% | +Rust | +{{ total.rust | round }}% | + +
Ruby | +{{ total.ruby | round }}% | +HTML | +{{ total.html | round }}% | + +CSS | +{{ total.css | round }}% | + +
Golang | +{{ total.golang | round }}% | +
Python | +{{ total.python | round }}% | +
By default, gitStream runs all applicable automations for every new PR and change to existing PR. If you want to test and experiment with new rules, gitStream supports a dry-run mode that will avoid making changes to your PRs. When you commit changes to any CM files found inside your repo's .cm/
directory, gitStream will switch to dry-run mode.
In dry-run mode, gitStream won't execute any automation rules on the PR. Instead, gitStream will parse all applicable automation rules and post a comment to the PR discussion that describes the actions that will be taken for normal PRs. A new comment will be added after every new commit.
Note
When in dry-run mode, incoming changes to the CM files are ignored. In other words, new automations and configurations won't take effect until you merge the PR.
Once you are satisfied with the results, you can merge your CM changes into the main branch to enable the new configurations.
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.
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:
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'
+
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:
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'
+
For a more detailed list of automations, check out the gitStream integrations page or automation library.
gitStream is triggered on new pull requests (PRs) for repositories that have gitStream installed. Upon triggering, gitStream collects context variables and evaluates the automation rules to determine which automation rules are relevant.
When a central cm
repository is set with the CI/CD runner, the events for PRs from all installed repositories shall be evaluated in the cm
repository pipeline, taking into account the organization level rules and the PR repository rules.
By default, gitStream evaluates any new commit that is pushed to the PR, triggering automation evaluation.
Additionally, if any of the automation rules reference the pr
context, gitStream shall trigger and will initiate automation rules evaluation even where there are changes to the PR title, descriptions, labels or comments.
This allows for greater flexibility in the automation process, ensuring that the relevant automation rules are evaluated and triggered when necessary. The execution model ensures that the automation process is streamlined, efficient, and effective.
gitstream supports an explicit triggering mechanism. When using explicit triggers, the automations will run only according to the defined triggers, which means the Implicit triggers will not work. Automations triggered by explicit triggers will also be invoked on draft
PRs
Use explicit triggers to enhance the control and customization of automations in gitStream, allowing users to define precisely when and how automations should be triggered based on various events and actions within pull requests.
Add the on
keyword to the file and/or to a specific automation to define explicit triggers. gitStream supports the following explicit triggers:
Trigger | Description |
---|---|
merge | Trigger when merging the PR |
pr_created | Trigger when the PR is created |
commit | Trigger on each commit after the creation of the PR |
comment_added | Trigger on each added comment |
label_added | Trigger on each added label |
label_removed | Trigger on removed label |
Explicit triggers are set per each automation block independently and can be configured at the file level, specific to each automation separately or a combination of the two. In case triggers are listed at the file level and specific automation, the automation will be triggered according to both triggers. If an automation block does not have explicit triggers configured, it will be triggered according to the default (implicit) triggers
Examples
assign code expert reviewer when the PR is created and after each commit
Explain code experts only if the label “suggest-reviewer” exists. The automation will be triggered after each commit and after each label addition. If the label “suggest-reviewer” exists, it will trigger the explain-code-experts
automation
In your repo permissions, make sure GitHub actions are permitted:
Go to Repo's settings > Actions > General > Actions permissions
Choose which repositories are permitted to use GitHub Actions.
[x] Allow all actions and reusable workflows
Like any other CI/CD automation, the source code is being scanned in the repo and is not shared with any external services. Only metadata that relates and affects the workflow is shared to allow rule based automation on the repo.
In order to support automations that either Approve or Merge PRs, GitHub API requires code write scope.
Any repo in GitHub is supported. More Git providers are planned soon.
Yes. When a merge queue is used, and gitStream is set as a required check, gitStream automation will be invoked with the merge event. The automation will set gitStream to a Completed
status and Skipped
conclusion to allow the PR merge.
Coming soon.
The .cm
file use YAML with JINJA2, in order for your favorite editor to choose automatically the right syntax, you can use modelines.
Add the following line to the top of the .cm
file (the default has it already):
Get a plug-in that enable modelines, popular ones are:
Go to our issues page and check if there are any similar issues already reported. If not, create a new issue with all the details so we can take a look.
Found a bug? Create a new item in the project's issues
JavaScript plugins that enable custom filter functions for gitStream. To learn how to use these examples, read our guide on how to use gitStream plugins.
Compares two software version numbers (e.g., "1.2.1" or "1.2b") and determines the type of version change. The first version to be compared, and the second are passed as argument 1 and 2 or as array of 2 items. When V1 > V2 the it means and upgrade.
Returns: string
- It returns a string of either: 'major' if the major version is incremented. 'minor' if the minor version is incremented. 'patch' if the patch version is incremented. 'downgrade' if the second version is lower than the first. 'equal' if both versions are equal. 'error' if the comparison is abnormal or cannot be determined.
License: MIT
Param | Type | Default | Description |
---|---|---|---|
versions | Array.<string> | V1 and V2 in Semver format | |
[lexicographical] | boolean | false | compares each part of the version strings lexicographically instead of naturally; this allows suffixes such as "b" or "dev" but will cause "1.10" to be considered smaller than "1.2". |
[zeroExtend] | boolean | true | changes the result if one version string has less parts than the other. In this case the shorter string will be padded with "zero" parts instead of being considered smaller. |
Example
/**
+ * @module compareSemver
+ * @description Compares two software version numbers (e.g., "1.2.1" or "1.2b") and determines the type of version change.
+ * The first version to be compared, and the second are passed as argument 1 and 2 or as array of 2 items.
+ * When V1 > V2 the it means and upgrade.
+ * @param {string[]} versions - V1 and V2 in Semver format
+ * @param {boolean} [lexicographical=false] - compares each part of the version strings lexicographically instead of naturally;
+ * this allows suffixes such as "b" or "dev" but will cause "1.10" to be considered smaller than "1.2".
+ * @param {boolean} [zeroExtend=true] - changes the result if one version string has less parts than the other. In
+ * this case the shorter string will be padded with "zero" parts instead of being considered smaller.
+ * @returns {string} It returns a string of either:
+ * 'major' if the major version is incremented.
+ * 'minor' if the minor version is incremented.
+ * 'patch' if the patch version is incremented.
+ * 'downgrade' if the second version is lower than the first.
+ * 'equal' if both versions are equal.
+ * 'error' if the comparison is abnormal or cannot be determined.
+ * @example {{ ["1.2.1", "1.2.3"] | compareSemver == "patch" }}
+ * @license MIT
+**/
+
+
+module.exports = (v1, v2, options = {}) => {
+ console.log("SEMVER", {v1, v2, options});
+
+ // support array as input
+ if (Array.isArray(v1) && v2 === undefined) {
+ [v1, v2] = v1; // Destructure the first two elements of the array into v1 and v2
+ }
+
+ const { lexicographical = false, zeroExtend = true } = options;
+ let v1parts = (v1 || "0").split('.');
+ let v2parts = (v2 || "0").split('.');
+
+ const isValidPart = x => lexicographical ? /^\d+[A-Za-zαß]*$/.test(x) : /^\d+[A-Za-zαß]?$/.test(x);
+
+ if (!v1parts.every(isValidPart) || !v2parts.every(isValidPart)) {
+ return 'error';
+ }
+
+ if (zeroExtend) {
+ const maxLength = Math.max(v1parts.length, v2parts.length);
+ v1parts = [...v1parts, ...Array(maxLength - v1parts.length).fill("0")];
+ v2parts = [...v2parts, ...Array(maxLength - v2parts.length).fill("0")];
+ }
+
+ const convertPart = x => {
+ const match = /[A-Za-zαß]/.exec(x);
+ return Number(match ? x.replace(match[0], "." + x.charCodeAt(match.index)) : x);
+ };
+
+ if (!lexicographical) {
+ v1parts = v1parts.map(convertPart);
+ v2parts = v2parts.map(convertPart);
+ }
+
+ for (let i = 0; i < v1parts.length; i++) {
+ if (v1parts[i] !== v2parts[i]) {
+ if (v1parts[i] < v2parts[i]) {
+ return 'downgrade';
+ }
+ switch (i) {
+ case 0: return 'major';
+ case 1: return 'minor';
+ case 2: return 'patch';
+ default: return 'error';
+ }
+ }
+ }
+
+ return 'equal';
+}
+
manifest:
+ version: 1.0
+
+automations:
+ bump_minor:
+ if:
+ - {{ bump == 'minor' }}
+ run:
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ bot `minor` version bumps are approved automatically.
+ bump_patch:
+ if:
+ - {{ bump == 'patch' }}
+ run:
+ - action: approve@v1
+ - action: merge@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ bot `patch` version bumps are approved and merged automatically.
+
+bump: {{ ["1.2.1", "1.2.3"] | compareSemver }}
+
Extract version bump information from Dependabot PRs description
Returns: Array.<string>
- V1 (to) and V2 (from)
License: MIT
Param | Type | Description |
---|---|---|
description | string | the PR description |
Example
/**
+ * @module extractDependabotVersionBump
+ * @description Extract version bump information from Dependabot PRs description
+ * @param {string} description - the PR description
+ * @returns {string[]} V1 (to) and V2 (from)
+ * @example {{ pr.description | extractDependabotVersionBump | compareSemver }}
+ * @license MIT
+**/
+
+
+module.exports = (desc) => {
+ if (desc && desc !== '""' && desc !== "''" ) {
+ const matches = /Bumps.*from ([\d\.]+[A-Za-zαß]*) to ([\d\.]+[A-Za-zαß]*)/.exec(desc);
+ if (matches && matches.length == 3) {
+ var [_, from, to] = matches;
+ // remove trailing dot on to
+ if (to[to.length - 1] === ".") {
+ to = to.slice(0, -1);
+ }
+ return [to, from];
+ }
+ }
+
+ return null;
+}
+
manifest:
+ version: 1.0
+
+automations:
+ bump_minor:
+ if:
+ - {{ bump == 'minor' }}
+ - {{ branch.name | includes(term="dependabot") }}
+ - {{ branch.author | includes(term="dependabot") }}
+ run:
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ Dependabot `minor` version bumps are approved automatically.
+ bump_patch:
+ if:
+ - {{ bump == 'patch' }}
+ - {{ branch.name | includes(term="dependabot") }}
+ - {{ branch.author | includes(term="dependabot") }}
+ run:
+ - action: approve@v1
+ - action: merge@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ Dependabot `patch` version bumps are approved and merged automatically.
+
+bump: {{ pr.description | extractDependabotVersionBump | compareSemver }}
+
Extract version bump information from Snyk PRs description
Returns: Array.<string>
- V1 (to) and V2 (from)
License: MIT
Param | Type | Description |
---|---|---|
description | string | the PR description |
Example
/**
+ * @module extractSnykVersionBump
+ * @description Extract version bump information from Snyk PRs description
+ * @param {string} description - the PR description
+ * @returns {string[]} V1 (to) and V2 (from)
+ * @example {{ pr.description | extractSnykVersionBump | compareSemver }}
+ * @license MIT
+**/
+
+
+
+module.exports = (desc) => {
+ if (desc && desc !== '""' && desc !== "''" ) {
+ const matches = /Upgrade.*from ([\d\.]+[A-Za-zαß]*) to ([\d\.]+[A-Za-zαß]*)/.exec(desc);
+ if (matches && matches.length == 3) {
+ var [_, from, to] = matches;
+ // remove trailing dot on to
+ if (to[to.length - 1] === ".") {
+ to = to.slice(0, -1);
+ }
+ return [to, from];
+ }
+ }
+
+ return null;
+}
+
manifest:
+ version: 1.0
+
+automations:
+ bump_minor:
+ if:
+ - {{ bump == 'minor' }}
+ - {{ branch.name | includes(term="snyk-update"") }}
+ - {{ branch.author | includes(term="snyk-update"") }}
+ run:
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ Snyk `minor` version bumps are approved automatically.
+ bump_patch:
+ if:
+ - {{ bump == 'patch' }}
+ - {{ branch.name | includes(term="snyk-update"") }}
+ - {{ branch.author | includes(term="snyk-update"") }}
+ run:
+ - action: approve@v1
+ - action: merge@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ Snyk `patch` version bumps are approved and merged automatically.
+
+bump: {{ pr.description | extractSnykVersionBump | compareSemver }}
+
Extract security issues information from Orca PR reviews
Returns: Object
- Findings Findings.infrastructure_as_code: { count: null, priority: '' }, Findings.vulnerabilities: { count: null, priority: '' }, Findings.secrets: { count: null, priority: '' },
License: MIT
Param | Type | Description |
---|---|---|
PR | Object | the gitStream's PR context variable |
Example
Usage example, that adds lables based on Orca Secuirty findings.
/**
+ * @module extractOrcaFindings
+ * @description Extract security issues information from Orca PR reviews
+ * @param {Object} pr - the gitStream's PR context variable
+ * @returns {Object} Findings
+ * Findings.infrastructure_as_code: { count: null, priority: '' },
+ * Findings.vulnerabilities: { count: null, priority: '' },
+ * Findings.secrets: { count: null, priority: '' },
+ * @example {{ pr | extractOrcaFindings }}
+ * @license MIT
+**/
+
+
+function getOrcaPropertyRating(lines, lineIdentifierRegex, findingsCellIndex) {
+ const matches = lines.filter(x => x.match(lineIdentifierRegex));
+ const [firstMatch] = matches;
+ const cells = firstMatch.split('|');
+ const [_, high, medium, low, info] = /"High"> ([\d]+).*"Medium"> ([\d]+).*"Low"> ([\d]+).*"Info"> ([\d]+)/
+ .exec(cells[findingsCellIndex])
+ .map(x => parseInt(x));
+ return {high, medium, low, info};
+}
+
+module.exports = (pr) => {
+ let orcaObject = {
+ infrastructure_as_code: { count: null, priority: '' },
+ vulnerabilities: { count: null, priority: '' },
+ secrets: { count: null, priority: '' },
+ };
+
+ // Orca comments are added as PR review
+ const orcaComment = pr.reviews.filter(x => x.commenter.includes('orca-security'));
+
+ if (orcaComment.length) {
+ const orcaCommentArray = orcaComment[orcaComment.length - 1].content.split('\n');
+
+ var priority = getOrcaPropertyRating(orcaCommentArray, /Infrastructure as Code/, 3);
+ orcaObject.infrastructure_as_code = {
+ count: priority.high + priority.medium + priority.low + priority.info,
+ priority,
+ };
+
+ var priority = getOrcaPropertyRating(orcaCommentArray, /Vulnerabilities/, 3);
+ orcaObject.vulnerabilities = {
+ count: priority.high + priority.medium + priority.low + priority.info,
+ priority,
+ };
+
+ var priority = getOrcaPropertyRating(orcaCommentArray, /Secrets/, 3);
+ orcaObject.secrets = {
+ count: priority.high + priority.medium + priority.low + priority.info,
+ priority,
+ };
+ }
+
+ return JSON.stringify(orcaObject);
+}
+
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in reports %}
+ label_orca_{{ item.name }}:
+ if:
+ - {{ item.count > 0 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'orca:{{ item.name }}'
+ {% endfor %}
+
+orca: {{ pr | extractOrcaFindings }}
+
+reports:
+ - name: introduced-cves
+ count: {{ orca.vulnerabilities.count }}
+ - name: iac-misconfigurations
+ count: {{ orca.infrastructure_as_code.count }}
+ - name: exposed-secrets
+ count: {{ orca.secrets.count }}
+
+colors:
+ red: 'b60205'
+
When used, create a secret TOKEN, and add it to the workflow file, in GitHub:
jobs:
+ gitStream:
+ steps:
+ - name: Evaluate Rules
+ uses: linear-b/gitstream-github-action@v1
+ env:
+ CODEOWNERS: ${{ secrets.GITSTREAM_CODEOWNERS }}
+
Resolves the PR's code owners based on the repository's CODEOWNERS file
Returns: Array.<string>
- user names
License: MIT
Param | Type | Description |
---|---|---|
files | Array.<string> | the gitStream's files context variable |
pr | Object | the gitStream's pr context variable |
token | string | access token with repo:read scope, used to read the CODEOWNERS file |
Example
/**
+ * @module getCodeowners
+ * @description Resolves the PR's code owners based on the repository's CODEOWNERS file
+ * @param {string[]} files - the gitStream's files context variable
+ * @param {Object} pr - the gitStream's pr context variable
+ * @param {string} token - access token with repo:read scope, used to read the CODEOWNERS file
+ * @returns {string[]} user names
+ * @example {{ files | getCodeowners(pr, env.CODEOWNERS_TOKEN) }}
+ * @license MIT
+**/
+
+
+const { Octokit } = require("@octokit/rest");
+const ignore = require('./ignore/index.js');
+
+async function loadCodeownersFile(owner, repo, auth) {
+ const octokit = new Octokit({
+ request: { fetch },
+ auth,
+ });
+
+ const res = await octokit.repos.getContent({
+ owner,
+ repo,
+ path: 'CODEOWNERS'
+ });
+
+ return Buffer.from(res.data.content, 'base64').toString()
+}
+
+function codeownersMapping(data) {
+ return data
+ .toString()
+ .split('\n')
+ .filter(x => x && !x.startsWith('#'))
+ .map(x => x.split("#")[0])
+ .map(x => {
+ const line = x.trim();
+ const [path, ...owners] = line.split(/\s+/);
+ return {path, owners};
+ });
+}
+
+function resolveCodeowner(mapping, file) {
+ const match = mapping
+ .slice()
+ .reverse()
+ .find(x =>
+ ignore()
+ .add(x.path)
+ .ignores(file)
+ );
+ if (!match) return false;
+ return match.owners;
+}
+
+module.exports = {
+ async: true,
+ filter: async (files, pr, token, callback) => {
+ const fileData = await loadCodeownersFile(pr.author, pr.repo, token);
+ const mapping = codeownersMapping(fileData);
+
+ const resolved = files
+ .map(f => resolveCodeowner(mapping, f))
+ .flat()
+ .filter(i => typeof i === 'string')
+ .map(u => u.replace(/^@/, ""));
+
+ const unique = [...new Set(resolved)];
+
+ return callback(null, unique);
+ },
+}
+
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ senior_review:
+ if:
+ - true
+ run:
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ experts | intersection(list=owners) }}
+
+experts: {{ repo | codeExperts(gt=10) }}
+owners: {{ files | codeowners(pr, env.CODEOWNERS) }}
+
Returns true if the username that is passed to this function is specified in a predefined list of users. This is useful if you want gitStream automations to run only for specified users.
Returns: boolean
- Returns true if the user is specified in the flaggedUsers list, otherwise false.
License: MIT
Param | Type | Description |
---|---|---|
Input | string | The GitHub username to check. |
Example
// Add users who you want to add to the flag list.
+const flaggedUsers = ["user1", "user2"];
+/**
+ * @module isFlaggedUser
+ * @description Returns true if the username that is passed to this function is specified in a predefined list of users.
+ * This is useful if you want gitStream automations to run only for specified users.
+ * @param {string} Input - The GitHub username to check.
+ * @returns {boolean} Returns true if the user is specified in the flaggedUsers list, otherwise false.
+ * @example {{ pr.author | isFlaggedUser }}
+ * @license MIT
+ */
+function isFlaggedUser(username) {
+ if (flaggedUsers.includes(username)) {
+ return true;
+ } else {
+ return false;
+ }
+};
+
+function containsString(arr, str) {
+ return arr.includes(str);
+};
+
+module.exports = isFlaggedUser;
+
+// Write code to test the isflaggeduser function
+console.log(isFlaggedUser("ben").toString());
+
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ detect_flagged_user:
+ if:
+ - {{ pr.author | isFlaggedUser }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: {{ pr.author }} is a gitStream user.
+
Filters can change the look and format of the source data, or even generate new data derived from the input values. What's important is that the original data is replaced by the result of transformations, and that's what ends up in rendered templates.
Note
Items marked with are under development and are not available yet.
The following functions are supported in addition to the built-in functions provided by Nunjucks.
Function | Input | Args | Output |
---|---|---|---|
capture Find and return the first occurrence of a regex in the input string | String | regex | [Objects] |
difference Given two lists, keep only items that are in the 1st list but not in the 2nd. | [Objects] | list | [Objects] |
every Checks whether all element in the list are true | [Bool] | - | Bool |
filter Reduce list of items into a list of same items that match the specified term | [String] [Object] | regex , term , list , attr | [String] [Object] |
includes Check if substring match | String | regex , term , list | Bool |
intersection Given two lists, keep only items that are in both lists. | [Objects] | list | [Objects] |
map Maps each object in a list into their specified attribute value | [Object] | attr | [Object] |
match Maps list of items into a list of booleans that match the specified term | [String] [Object] | regex , term , list attr | [Bool] |
nope Checks whether all element in the list are false | [Bool] | - | Bool |
reject Inverse of filter , the result list contains non-matching items | [String] [Object] | regex , term , list , attr | [String] [Object] |
some Checks whether at least one element in the list is true | [Bool] | - | Bool |
Function | Input | Args | Output |
---|---|---|---|
allDocs Checks the list includes only documents | files | - | Bool |
allImages Checks the list includes only images | files | - | Bool |
allTests Checks the list includes only tests | files | - | Bool |
codeExperts Get list of contributors based on expert reviewer model results | repo | gt , lt | [String] |
estimatedReviewTime Estimated review time in minutes | branch | - | Integer |
extensions Lists all the unique file extensions | [String] | - | [String] |
extractJitFindings Get an object with a summary of the findings found by the Jit scan | pr | - | Object |
extractSonarFindings Get an object with a summary of the findings found by the SonarCloud scan | pr | - | Object |
explainRankByGitBlame Short markdown text explaining rankByGitBlame results | repo | gt , lt | [String] |
isFirstCommit Checks if its the author first commit in the repo | repo.contributors | String | Bool |
isFormattingChange Checks that only formatting changed | [FileDiff ] | - | Bool |
mapToEnum return the enum value matches to the input key | String | Enum object | Object |
matchDiffLines Match every line in diff | [FileDiff ] | regex , ignoreWhiteSpaces | [Bool] |
rankByGitActivity Get list of contributors based on git-commit activity | repo | gt , lt | [String] |
rankByGitBlame Get list of contributors based on git-blame results | repo | gt , lt | [String] |
Some functions support named arguments, many of these repeat in different functions.
term
- a single string, used as a substring to match with the matched item.
list
- a list of strings, trying to match any of the listed substrings with the matched item.
regex
- a single string, used as a regular expression with the matched item. A regular expression can be created just like JavaScript, but needs to be prefixed with r, for example, r/^foo.*/g
, for more info see Nunjucks.
attr
- a key in the element to use when doing the requested operation.
For example, the following expressions provide an identical result:
- {{ 'something' | includes(regex=r/^some.*/) }}
+- {{ 'something' | includes(term='some') }}
+- {{ 'something' | includes(list=['some']) }}
+
capture
Extract the first match of the regex in the input string. If no match is found, the function returns an empty string.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | String | The string to find the match in |
regex | Input | String | Search term to match with the input string |
- | Output | Bool | The first substring that match the provided regex |
For example, the following line will extract the substring "hello wo" from the input
difference
Given two lists, keep only items that are in the 1st list but not in the 2nd.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Objects] | List of objects to inspect. |
list | Input | [Objects] | List of objects to exclude. |
- | Output | [Objects] | Returns a list of objects containing items that exist in one input, but not in the other. |
every
Checks whether all element in the list are true
. In case the list of elements is empty, it will return false
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Bool] | List of booleans |
- | Output | Bool | Returns true when all list items are true |
For example, check that all changes are in either 'src' or 'dest' directories:
filter
Creates a shallow copy of a portion of a given list, filtered down to just the elements that match the given term. You can use either a single term, regex, or a list of terms to match with.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [String] [Object] | The list of strings to match, or list of objects if attr is used |
term regex list | Input (either) | String String [String] | Search term to match with the input items |
attr | Input (optional) | String | match a named attribute in the input object |
- | Output | [String] [Object] | The list with only the matching items |
For example, check if all changes to JavaScript files are in tests directory:
For example, check if all changes to JavaScript files are formatting:
includes
Determines whether a string includes a certain substring. You can use either a single term, regex, or a list of terms to match with.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | String | The string you want to check for matching substrings |
term regex list | Input (either) | String String [String] | Substring term to match |
- | Output | Bool | true if search terms matches |
Check string matches either of the terms:
intersection
Given two lists, keep only items that are in both lists.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Objects] | List of objects to inspect. |
list | Input | [Objects] | List of objects to check for intersection. |
- | Output | [Objects] | Returns a list of objects containing items that intersect between the two lists. |
map
Creates a new list populated with the values of the selected attribute of every element in the input list.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Object] | The list of objects to map, see context for valid inputs |
attr | Input | String | Object attribute to select |
- | Output | [Object] | List of the selected object attributes |
For example, the source.diff.files
context holds a list of FileDiff
, each has new_file
attribute. You can create a list of all the new file names by mapping to the new_file
attribute and then check if there are changes to any handler.js
file:
match
Return true
for each element in the list that match the search term.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [String] [Object] | The list of strings or if attr used the list of objects |
term regex list | Input (either) | String String [String] | Search term to match |
attr | Input | String | match a named attribute in the input object |
- | Output | [Bool] | true for every matching item |
For example, to check if all code changes are in the tests
directory:
For example, to check if there are code changes with specific function call:
nope
The inverse of every
, checks whether all elements in the list are false
. In case the list of elements is empty, it will return true
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Bool] | List of booleans |
- | Output | Bool | Returns true when all list items are false |
For example, check that no changes in either 'src' or 'dest' directories:
reject
Creates a shallow copy of a portion of a given list, filtered down to just the elements that do not match the given term. You can use either a single term, regex, or a list of terms to match with.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [String] [Object] | The list of strings to match, or list of objects if attr is used |
term regex list | Input (either) | String String [String] | Search term to match with the input items |
attr | Input (optional) | String | match a named attribute in the input object |
- | Output | [String] [Object] | The list with only the non-matching items |
For example, check if all changes, but JavaScript files are in tests directory:
For example, check if all changes except for config.json
files are formatting:
some
Checks whether any element in the list is true
. In case the list of elements is empty it will return false
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Bool] | List of booleans |
- | Output | Bool | Returns true when any of the items is true |
allDocs
Return true
if the input list includes only documents based on file extensions.
Doc files extensions are: md
, mkdown
, txt
, rst
, adoc
, except for requirements.txt
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | files | The list of changed files with their path |
- | Output | Bool | true if all file extensions are of docs |
In case you want to exclude more files, like all txt
under the requirements
directory, add another check:
allImages
Return true
if the input list includes only images based on file extensions.
Image file extensions are: svg
, png
, gif
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | files | The list of changed files with their path |
- | Output | Bool | true if all file extensions are of images |
allTests
Return true
if the input list includes only tests based on the file's path and name.
To identify as test the file must include the word test
or spec
in its name or path, it is checked using this regex: [^a-zA-Z0-9](spec|test|tests)[^a-zA-Z0-9]
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | files | The list of changed files with their path |
- | Output | Bool | true if all file tests are based on name and path |
codeExperts
When requesting a review for a pull request, it's important to select a reviewer who has a deep understanding of the relevant code area, the domain problem, and the framework being used. This ensures that the reviewer can provide specific and informed feedback, rather than general comments that may not take into account the context in which the issue was solved.
The filter provides the list of most qualified contributors based on git-blame
and git-commit
results to determine who has been most active in the relevant code area, and then combines this information into a score between 0 and 100. The commit activity is scored higher for recent commits, which ensures that those who are actively contributing to the codebase are given higher priority as potential reviewers. The result will be limited to 2 users and shall not include the PR author.
The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame
output. When gitStream cannot map the Git user to a Git provider user it will be dropped from the output list, hence the list may contain less than 100% of the lines.
Note
The codeExperts
filter function calls gitStream app API with the repo
context to calculate the estimated review time value.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | repo | The repo context variable |
lt | Input | Integer | Filter the user list, keeping those below the specified threshold |
gt | Input | Integer | Filter the user list, keeping those above the specified threshold |
- | Output | [String] | Up to 2 users, sorted by best match first (it won't include the PR author) |
For example:
automations:
+ code_experts:
+ if:
+ - true
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | codeExperts(gt=10) }}
+
estimatedReviewTime
Returns the estimated review time in minutes based on statistical model. The model uses the amount of additions and deletions statistics for each file type with additional information about the commits and base branch.
Note
The estimatedReviewTime
filter function calls gitStream app API with the branch
context to calculate the estimated review time value.
The following files are excluded when calculating this value:
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | branch | Branch meta data |
- | Output | Integer | the estimated time for review in minutes |
The following files are automatically excluded from the estimated review time calculation.
File type | Filter type | Values |
---|---|---|
Data | Extension | ini csv xls xlsx xlr doc docx txt pps ppt pptx dot dotx log tar rtf dat ipynb po profile object obj dxf twb bcsymbolmap tfstate pdf rbi pem crt svg png jpeg jpg ttf |
Data | Regex | .*dist/.*\.js$ .*public/assets/.*\.js$ |
Lock | Regex | .*package-lock|packages\.lock|package)\.json$ |
Lock | File | yarn.lock gemfile.lock podfile.lock cargo.lock composer.lock pipfile.lock gopkg.lock |
Lock | Regex | .*gradle\.lockfile$ .*lock\.sbt$ |
Pipeline | Regex | .*ci\.yml$ |
Tip
You can also filter more files, using config.ignore_files
.
extensions
Expects files
and provide a list of all unique file extensions.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | files | The list of changed files with their path |
- | Output | [String] | List of all unique file extensions |
For example, check that only one file type was changed:
extractJitFindings
Available in GitHub only
This filter is currently availalbe only in GitHub
Get an object with a summary of the findings found by Jit scan. This filter is relevant only for repos that use Jit to scan PRs
The pr
context includes all the reviews in the pull request, including the reviews written by the Jit bot, along with all the comments (conversations) to the review.
This filter reads and parses the reviews with Jit's findings, making them available for use inside the .cm
file automations.
The output is an object of the following format:
{
+ "vulnerabilities": [{
+ "security_control": 'string',
+ "type": 'string',
+ "description": 'string',
+ "severity": 'string',
+ "summary": 'string'
+ }],
+ "metrics": {
+ "HIGH": number,
+ "MEDIUM": number,
+ "LOW": number,
+ "INFO": number
+ }
+}
+
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | pr | The pr context variable |
- | Output | Object | The object contains the summary of Jit's scan |
Example of the filter output
{
+ "vulnerabilities": [
+ {
+ "security_control": "Static Code Analysis Js",
+ "type": "Codsec.Javascriptnosql-Injection.Nosql-Injection",
+ "description": "Putting request data into a mongo query can leadto a NoSQL Injection. Be sure to properly sanitize thedata if you absolutely must pass request data into a query.",
+ "severity": "HIGH",
+ "summary": "Jit Bot commands and options (e.g., ignore issue)"
+ },
+ {
+ "security_control": "Secret Detection",
+ "type": "Private-Key",
+ "description": "Private Key",
+ "severity": "HIGH",
+ "summary": "Jit Bot commands and options (e.g., ignore issue)"
+ }
+ ],
+ "metrics": {
+ "HIGH": 2,
+ "MEDIUM": 0,
+ "LOW": 0,
+ "INFO": 0
+ }
+}
+
Assign the output to a variable
Add a label if Jit detected secrets in the PR
automations:
+ add_bugs_label:
+ if:
+ - {{ jit.metrics.HIGH > 0 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "Vulnerable code!""
+
extractSonarFindings
Available in GitHub only
This filter is currently availalbe only in GitHub
Get an object with a summary of the findings found by the SonarCloud scan. This filter is relevant only for repos that use SonarCloud to scan PRs
The pr
context includes all the comments added to the pull request, including the comment written by the SonarCloud bot that holds a summary of its scan.
This filter reads and parses the comment with SonarCloud's scan summary and makes them available to use inside the .cm
file automations.
The output is an object of the following format:
{
+ "bugs": {
+ "count": number,
+ "rating": 'string' //('A'-'E')
+ },
+ "code_smells": {
+ "count": number,
+ "rating": 'string' //('A'-'E')
+ },
+ "vulnerabilities": {
+ "count": number,
+ "rating": 'string' //('A'-'E')
+ },
+ "security_hotspots": {
+ "count": number,
+ "rating": 'string' //('A'-'E')
+ },
+ "duplications": number,
+ "coverage": number
+}
+
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | pr | The pr context variable |
- | Output | Object | The object contains the summary of SonCloud's scan |
Example of the filter output
{
+ "bugs": {
+ "count": 1,
+ "rating": 'B'
+ },
+ "code_smells": {
+ "count": 2,
+ "rating": 'B'
+ },
+ "vulnerabilities": {
+ "count": 2,
+ "rating": 'E'
+ },
+ "security_hotspots": {
+ "count": 0,
+ "rating": 'A'
+ },
+ "duplications": 3,
+ "coverage": 70
+}
+
Assign the output to a variable
Add a label with the number of bugs if the bugs rating is other than 'A', and use mapToEnum to set its color
automations:
+# Add Bugs label
+ show_bugs_count:
+ if:
+ - {{ sonar.bugs.count > 0}}
+ run:
+ - action: add-label@v1
+ args:
+ label: '🐞 x {{ sonar.bugs.count }} Bugs'
+ color: {{ sonar.bugs.rating | mapToEnum(enum = colors) }}
+
+colors:
+ A: '05AA02'
+ B: 'B6D146'
+ C: 'EABE05'
+ D: 'DF8339'
+ E: 'D4343F'
+
explainRankByGitBlame
This filter helps to explain the results of rankByGitBlame
, the output is in Markdown format that can be used in a PR comment.
The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame
output. Git users that could not be automatically mapped are marked with *
. To map these users, you can add user_mapping
see instructions here.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | repo | The repo context variable |
lt | Input | Integer | Filter the user list, keeping those below the specified threshold |
gt | Input | Integer | Filter the user list, keeping those above the specified threshold |
- | Output | String | Explaining rankByGitBlame results in markdown format |
Note
Each contributor's result is rounded down to the nearest integer, so the total may add up to less than 100%.
For example:
automations:
+ the_right_reviewer:
+ if:
+ - true
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | rankByGitBlame(gt=50) }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ {{ repo | explainRankByGitBlame(gt=50) }}
+
Note the comment starts with |
and a new-line
as explainRankByGitBlame
generates a multiline comment.
isFirstCommit
Return true
if it's the author first commit in the repo.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | repo.contributors | List of contributors in the repo |
- | Input | String | The contributor name |
- | Output | Bool | true if its the first commit of the selected contributor |
if:
+ - {{ repo.contributors | isFirstCommit(branch.author) }}
+run:
+ - action: add-comment@v1
+ args:
+ comment: "Welcome {{branch.author}}!"
+
isFormattingChange
Return true
if all file diffs are validated as formatting changes. This filter function works for JavaScript, TypeScript, Python, JSON, YAML and HTML.
gitStream determines formatting changes by minifying the source code for the incoming changes and the existing code and comparing them. If they are identical, this filter function returns true
. If any unsupported languages are contained in the PR, gitStream will return false
.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | source.diff.files | List of file diffs |
- | Output | Bool | true if the all code changes are non functional |
mapToEnum
Get the enum value matches to the input key
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | String | The key name |
enum | Input | Enum Object | The enum object to which the input string should be matched |
- | Output | Object | The value of the input key in the input enum object |
For example, set a label color according to names in the enum:
automations:
+ label_color:
+ if:
+ - true
+ run:
+ - action: add-label@v1
+ args:
+ label: 'Blue label'
+ color: {{ "blue" | mapToEnum(enum = colors) }}
+
+colors:
+ red: 'FF0000'
+ green: '00FF00'
+ blue: '0000FF'
+ yellow: 'FFFF00'
+
matchDiffLines
Checks diff for matching lines.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | [Object] | The list of objects |
regex | Input | String | Regex term to match with the input items, use \\ for \ |
ignoreWhiteSpaces | Input | Bool | false by default, match a named attribute in the input object |
caseSensitive | Input | Bool | true by default, ignore case when matching terms |
- | Output | [Bool] | true for every matching object |
For example, to check if all the changes are of adding prints and ignore white spaces:
{{ source.diff.files | matchDiffLines(regex=r/^\+.*console\.log/, ignoreWhiteSpaces=true) | every }}
+
rankByGitActivity
Get list of contributors based on git-commit
activity.
The repo
context includes all the changed files, for each file it includes each contributor number of lines changed every week over the last 52 weeks, based on git-commit
.
These functions compare each contributor changes per week and yield an average percentage of contribution for any given file. For example, in a certain week a file had 500 line changed, 200 by a first user, while 3 other users changed 100 lines each. So the score for the first user in that week will be 40 (200/500 in %). The function then average the score for each user for the selected time period.
Then you can use the thresholds to get the right reviewer.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | repo | The repo context variable |
weeks | Input | Integer | The number of last weeks to include |
lt | Input | Integer | Filter the user list, keeping those below the specified threshold |
gt | Input | Integer | Filter the user list, keeping those above the specified threshold |
- | Output | [String] | The list of users based on their code score comparison |
Check if the branch author is a rookie
rankByGitBlame
Get list of contributors based on git-blame
results
The repo
context includes all the changed files, for each file it includes the contributors' percentage of lines in the file, based on git-blame
.
This function sums all these percentages per user and yield an average percentage of contribution. Then you can use the thresholds to get the right reviewer.
The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame
output. When gitStream cannot map the Git user to a Git provider user it will be dropped from the output list, hence the list may contain less than 100% of the lines.
Argument | Usage | Type | Description |
---|---|---|---|
- | Input | repo | The repo context variable |
lt | Input | Integer | Filter the user list, keeping those below the specified threshold |
gt | Input | Integer | Filter the user list, keeping those above the specified threshold |
- | Output | [String] | The list of users based on their code score comparison, sorted by rank - first has highest score |
Example of the filter output, note the output are GitHub users in the example:
Get the most significant contributors for the PR files:
Check if the branch author is a rookie
Welcome to gitStream Playground! This platform allows you to thoroughly test gitStream automations before deploying them into the .cm
rule file on any GitHub pull request of your choice.
To access gitStream Playground, visit https://app.gitstream.cm/playground. To be able to test automations of private repository PRs, log in with your GitHub account credentials.
The gitStream Playground interface consists of the following sections:
estimated_time_to_review
and safe_changes
are provided by default.Output
- shows syntax errors when the .cm
automation syntax is wrong. After running gitStream - it shows the expected result of the automation on the chosen Pull Request.Context Variables
- Shows the values of all Context variables of the chosen Pull Request.On GitHub, navigate to any pull request, copy its link, and paste it onto the "Pull request link" box. If the PR is part of a private repo, you must also log in to the playground with a GitHub user accessible to this repository.
.cm
editor.The automation results will be shown in the "Output" tab at the bottom of the interface. Context Variables will be shown in the "Context Variables" tab.
For additional assistance or to provide feedback, please open an issue on our GitHub issues page
Install gitStream
Before you can complete the gitStream setup process, you need to install the gitStream app to your GitHub organization.
You can set up gitStream for a single repo or your entire GitHub organization. Select the tab below for the instructions you want.
Single Repo Setup
You must implement two main components for gitStream to function for a single GitHub repo. The first is a configuration file that defines the workflow automations to execute for the repo. The second is 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 will contain a YAML configuration that determines the workflows that run on the repo, and 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 setup some basic workflow automations.
# -*- 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/examples/
+manifest:
+ version: 1.0
+
+
+automations:
+ # Add a label that indicates how many minutes it will take to review the PR.
+ 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 ) }}
+ # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
+ 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 }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is missing a Jira ticket reference in the title or description.
+ Please add a Jira ticket reference to the title or description of this PR.
+ # Post a comment that lists the best experts for the files that were modified.
+ explain_code_experts:
+ if:
+ - true
+ run:
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
+
+# +----------------------------------------------------------------------------+
+# | Custom Expressions |
+# | https://docs.gitstream.cm/how-it-works/#custom-expressions |
+# +----------------------------------------------------------------------------+
+
+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}/) }}
+
+colors:
+ red: 'b60205'
+ yellow: 'fbca04'
+ green: '0e8a16'
+
Github Actions
Once your gitStream configuration file is setup, 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: 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 }}
+
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 will contain 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 set up instructions for a single repo, your .cm
files should be placed in the repository's root directory.
# -*- 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/examples/
+manifest:
+ version: 1.0
+
+
+automations:
+ # Add a label that indicates how many minutes it will take to review the PR.
+ 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 ) }}
+ # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
+ 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 }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is missing a Jira ticket reference in the title or description.
+ Please add a Jira ticket reference to the title or description of this PR.
+ # Post a comment that lists the best experts for the files that were modified.
+ explain_code_experts:
+ if:
+ - true
+ run:
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
+
+# +----------------------------------------------------------------------------+
+# | Custom Expressions |
+# | https://docs.gitstream.cm/how-it-works/#custom-expressions |
+# +----------------------------------------------------------------------------+
+
+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}/) }}
+
+colors:
+ red: 'b60205'
+ yellow: 'fbca04'
+ green: '0e8a16'
+
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: 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 }}
+
gitStream will now do these two things.
When a PR is created or changed, apply or update a label that provides an estimated time to review.
When a new PR is created, comment with a list of code experts.
How gitStream Works
Read our guide: How gitStream Works to get an overview of the gitStream syntax and automation lifecycle.
Permissions | Reason |
---|---|
Write access to dedicated gitStream app files | Used to set up the gitStream workflow files |
Write access to code | To allow gitStream to approve PRs once all conditions are met |
Read access to administration, issues, and metadata | To get the user team membership, and branch protection settings |
Read and write access to actions, checks, pull requests, and workflows | Trigger workflows, create and update pull requests and their checks, and modify workflow files |
User email | Used to identify users |
You can configure Github to require gitStream checks to pass before PRs can be merged using branch protection rules.
Run a gitStream check before continuing
You need to run a check using your gitStream configuration at least once before it can be set as a required check. Make sure to open at least 1 PR before doing this setting.
Here are the steps to configure gitStream in your repo's branch protection rules.
settings
Code and automation
> Branches
Branch protection rules
for your desired branchRequire status checks to pass before merging
status checks in the last week for this repository
gitStream.cm
as required checkTo ensure gitStream runs on self-hosted GitHub Actions runners, follow these steps to configure it:
Configure Self-Hosted Runners with Ensure you have self-hosted runners set up for your GitHub organization or repository. Refer to the GitHub documentation on self-hosted runners and Using self-hosted runners in a workflow for detailed instructions.
Install Docker and Git on Self-Hosted Runners Make sure your self-hosted runners have Docker and Git installed. These are essential dependencies for gitStream to function properly. You can follow the official installation guides for Docker and Git.
Update GitHub Actions Configuration Open the gitStream GitHub Actions workflow file (.github/workflows/gitstream.yml
) and update the runs-on
field to specify that the gitStream job must run on self-hosted runners. For example:
Save and Commit Save your changes to the workflow file and commit them to your repository.
Test with a Sample PR Create a sample pull request and observe gitStream's behavior. It will use the configured self-hosted runners.
Configure in your GitHub organization, and choose Uninstall "gitStream.cm"
Prerequisites
GitLab Installation Overview
gitStream automation rules are executed on behalf of the user account that is logged in when you install the gitStream service. This account must have the Maintainer
role.
We recommend creating a dedicated account for this purpose so you can more easily control access to individual repos. You can also use your professional or personal GitLab account for this, but that would result in all automations being executed under that account.
Use this account when you install gitStream
Make sure you're logged into this user account in the web browser that you use to click the installation button in step 4.
You can set up gitStream for a single repo or your entire GitLab organization. Select the tab below for the instructions you want.
Single Repo Setup
Create a .cm/gitstream.cm
rules file in your repository's default branch (usually master
or main
). This file will contain a YAML configuration that determines the workflows that run on the repo, and you can name it anything you want as long as it ends in .cm
Example Configuration
Here is an example of a gitStream configuration file you can use to setup some basic workflow automations.
# -*- 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/examples/
+manifest:
+ version: 1.0
+
+
+automations:
+ # Add a label that indicates how many minutes it will take to review the PR.
+ 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 ) }}
+ # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
+ 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 }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is missing a Jira ticket reference in the title or description.
+ Please add a Jira ticket reference to the title or description of this PR.
+ # Post a comment that lists the best experts for the files that were modified.
+ explain_code_experts:
+ if:
+ - true
+ run:
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
+
+# +----------------------------------------------------------------------------+
+# | Custom Expressions |
+# | https://docs.gitstream.cm/how-it-works/#custom-expressions |
+# +----------------------------------------------------------------------------+
+
+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}/) }}
+
+colors:
+ red: 'b60205'
+ yellow: 'fbca04'
+ green: '0e8a16'
+
GitLab Group Setup
Group rules are ideal when you want to enforce consistent rules across every repo in your GitLab group. You can define them by creating a special repository named cm
in the parent group for the git repositories you want to run gitStream on. Here, you can add automation files that will apply to all repositories within that group.
Create a cm
project (repository) in your GitLab group, and create a gitstream.cm
rules file in the root directory of your cm
repository's default branch (usually master
or main
). This file will contain a YAML configuration that determines the workflows that run on your organization's repos. You can name the CM file anything you want as long as it ends in .cm
Configuration files go in the repo's root directory.
Unlike the set up instructions for a single repo, your .cm
files should be placed in the repository's root directory.
Example Configuration
Here is an example of a gitStream configuration file you can use to setup some basic workflow automations.
# -*- 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/examples/
+manifest:
+ version: 1.0
+
+
+automations:
+ # Add a label that indicates how many minutes it will take to review the PR.
+ 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 ) }}
+ # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
+ 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 }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is missing a Jira ticket reference in the title or description.
+ Please add a Jira ticket reference to the title or description of this PR.
+ # Post a comment that lists the best experts for the files that were modified.
+ explain_code_experts:
+ if:
+ - true
+ run:
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
+
+# +----------------------------------------------------------------------------+
+# | Custom Expressions |
+# | https://docs.gitstream.cm/how-it-works/#custom-expressions |
+# +----------------------------------------------------------------------------+
+
+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}/) }}
+
+colors:
+ red: 'b60205'
+ yellow: 'fbca04'
+ green: '0e8a16'
+
Once your gitStream configuration file is setup, you need a GitLab CI configuration file to trigger gitStream automations. If you haven't already, create a cm
project (repository) in your GitLab group. It should be created in the same group or a parent group of the target repositories. Create a .gitlab-ci.yml
file in your new cm
repository's default branch (usually master
or main
) and add the following configuration:
# Code generated by gitStream - DO NOT EDIT
+stages:
+ - gitstream-main
+image: docker:latest
+services:
+ - docker:dind
+before_script:
+ - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
+
+gitstream-job:
+ stage: gitstream-main
+ only:
+ variables:
+ - $GITSTREAM_MAIN_JOB
+ except:
+ variables:
+ - $GITSTREAM_BLOCK_MERGE
+ script:
+ - apk update && apk add git && apk add docker
+ - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo
+ - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm
+ - cd gitstream && cd repo && git fetch --all && git checkout $base_ref && git pull && ls && git checkout $head_ref && git pull && ls
+ - docker pull gitstream/rules-engine:latest
+ - |
+ docker run -v $CI_PROJECT_DIR/gitstream:/code \
+ -e HEAD_REF=$head_ref \
+ -e BASE_REF=$base_ref \
+ -e CLIENT_PAYLOAD="$client_payload" \
+ -e RULES_RESOLVER_URL=$resolver_url \
+ -e RULES_RESOLVER_TOKEN=$resolver_token \
+ -e DEBUG_MODE=true gitstream/rules-engine:latest
+
If you successfully completed these instructions, gitStream will now do these two things.
When a PR is created or changed, apply or update a label that provides an estimated time to review.
When a suggest-reviewers
label is applied to a PR, gitStream will comment with a list of code experts.
How gitStream Works
Read our guide: How gitStream Works to get an overview of the gitStream syntax and automation lifecycle.
The required permissions are:
Permissions | Reason |
---|---|
Read/Write API | To get notified on MR changes and allow gitStream to approve MRs once all conditions are met |
Read repository | To read and check rules over the code changes on monitored repositories |
Read user profile | Used to identify users |
Does gitStream support the ability to block merges?"
gitStream actions that blocks MR merge are not supported at the moment.
What is a gitStream service account?
gitStream executes rules on behalf of the user account that was used to install it. We recommend using a new dedicated account in GitLab for installing gitStream.
You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab organization. These files end with a .cm
extension, and they outline automations that will run whenever someone opens a new PR or makes changes to an existing PR.
CM files contain a combination of YAML and Jinja2 to build rules that follow an "if this, then that" approach to triggering and executing automations. This, combined with templating and gitStream-specific functions gives you a highly-flexible framework for building custom CM automations.
All CM files must have a section that starts with automations:
that contains one or more custom automations that will trigger for the repo. gitStream is triggered every time someone opens a new PR or changes an existing PR. Once activated, gitStream searches for applicable CM files and executes the automations that are listed inside them.
Here is an example of the basic components that are required in every CM file.
Required CM Components
Please note, this is not a valid CM automation, it is only for illustrative purposes.
Info
When editing CM files, make sure you preserve the indentation in the examples because, like YAML, gitStream uses Python-style indentation to indicate nesting.
Automation actions specify the desired automations that should be triggered when all conditions are met. Each automation must include an if
condition and a run
section. The conditions are evaluated whenever someone creates a PR or makes changes to an existing PR; multiple conditions can be listed for a single automation, but they must all be true to invoke the actions. You can have any number of actions listed in one automation. Actions are invoked one-by-one in no particular order. PRs that are marked as Draft are ignored by default, but you can control that using explicit triggers.
Basic Automation Example
This example defines an automation named welcome_newcomer
that post a comment to welcome anyone who submits their first PR to the repo.
Context variables are pre-defined objects that gitStream provides as the input data you will need to build your automations. These variables enable you to access information about things like the file names and paths, the person who submitted the PR, or what code was changed.
Filter functions are functions you can call and apply to variables. They are called with a pipe operator |
and can take arguments inside parentheses ( )
. The logic expressions are based on Jinja2 syntax, supported by the Nunjucks library.
Context Variable and Filter Function Example
The following statement passes the context variable files
to the filter function match
which uses an optional list of sensitive filepaths that would need to be defined later in the CM file, and returns true if any of the files match the list as indicated by the some
filter function.
You can also apply Nunjucks logic operators to filters
Logic Operators Example
This example inverts the previous example using the keyword not
.
Jinja templating makes it easy to write custom expressions that can be invoked elsewhere in your CM files. This makes it easy to reuse data, define custom criteria, and keep your configuration files cleaner so they're easier to manage.
Custom Expressions Example
This example contains two custom expressions; is:
contains a context variable and some filter functions that are invoked in the sensitive_review
automation via is.sensitive
, and sensitive directories
contains a list of directory paths that will be matched in the filter function.
You can provide gitStream with a list of specific files to ignore for all automations listed in the same CM file. To do so, add a configuration:
section to the CM file that you want to apply the exclusion list to. In the configuration section, add a list of files as an argument to the ignore_files:
key.
How to Ignore Files
To ignore a list of files, add a config.ignore_files
to you CM file like this:
Similarly, if you are using gitStream for your entire git organization, you can specify repos to ignore in the gitstream.cm
file in the root directory of your cm repo.
You can provide any number of CM files and automations for gitStream to process and you can freely combine organization-level automations with automations inside individual repos. There are two important things you need to keep in mind when doing this.
First, when a repository defines the same automation as an organization-level rule, the repository automation will take precedence and override the organization automation. The CM file name and the automation name must both match for this to take effect because gitStream identifies all automations based on a combination of both. For example, if you have a gitstream.cm
file that contains an automation named my_automation
, gitStream will identify that as gitstream/my_automation
.
Second, no priority is given to individual automations. Instead, gitStream collects all applicable automations for a given PR and processes them all at once.
Write your first automation.
The best way to familiarize yourself with CM syntax is to build automations, and we've covered enough info for you to start!
If you're ready to start writing automations, check out our guide: Write Your First Automation.
Once you have gitStream installed and have run some automations, you can view details about them at app.gitstream.com. To view gitStream data, you will need to login with your GitHub account and have access to an organization that has run gitStream automations.
Once gitStream is installed and configured, there are several services that will interact with your repository whenever a PR is created or changed:
Whenever a new PR is opened or an existing PR is changed, the following process occurs:
linear-b/gitstream-github-action@v1
on the repository, which looks for two things:.cm/*.cm
Here is a diagram that illustrates how things work behind the scenes:
sequenceDiagram
+ autonumber
+ Git Provider API->>gitStream app: PR Notification
+ activate gitStream app
+ gitStream app->>gitStream CI/CD script: Execute CI/CD Action
+ activate gitStream CI/CD script
+ gitStream CI/CD script->>gitStream agent: CM Metadata
+ activate gitStream agent
+ gitStream agent->>gitStream app: Applicable Automations
+ deactivate gitStream agent
+ deactivate gitStream CI/CD script
+ loop Automations
+ loop Actions
+ gitStream app->>Git Provider API: Update PR
+ end
+ end
+ deactivate gitStream app
Upon completion, gitStream will show one of the following three statuses: gitStream checks have a 10-minute timeout for fail-safe reasons. If the check exceeds this time limit, the result will be displayed as Neutral - Skipped.
Avoid using these words when naming your automations, actions, or other components.
gitStream reserved words:
allDocs
allImages
allTests
automations
codeExperts
config
difference
estimatedReviewTime
explainCodeExperts
explainRankByGitBlame
extractJitFindings
extractSonarFindings
extensions
every
filter
includes
isFirstCommit
isFormattingChange
intersection
manifest
map
mapToEnum
match
matchDiffLines
nope
rankByGitActivity
rankByGitBlame
reject
some
Nunjucks reserved words:
abs
asyncAll
asyncEach
batch
block
call
capitalize
center
default
dictsort
dump
e
escape
extends
filter
first
float
for
forceescape
groupby
if
import
include
indent
int
join
last
length
list
lower
macro
nl2br
raw
reject
rejectattr
replace
reverse
round
safe
select
selectattr
set
slice
sort
string
striptags
sum
title
trim
truncate
upper
urlencode
urlize
verbatim
wordcount
You can add support for .cm
in your code editor, see FAQ.
If you find an issue with these docs or with gitStream itself, please search the gitStream issues page and create an issue if one doesn't already exist for your problem.
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Auto-Merge PRs
Not all PRs need extensive review policies that loop in multiple experts. gitStream lets you auto-merge safe changes, small fixes, PRs from trusted teams, and anything else you want to unblock the review process to keep your team focused on their work.
Contextual Labels
Reduce the mental burden of code reviews with labels that provide a high degree of context. Indicate an estimated time to review or flag potential issues with Jira information, missing tests, deleted files, and more.
Review Assignment
Identifying the correct people to review a PR can take time, particularly for complex projects and repos requiring deep expertise. Assign code experts to review complex PRs, notify your security team about sensitive changes, and automatically assign reviewers based on the contents of the PR.
Automated Change Requests
Reduce code review noise by catching issues before anyone invests precious time. Flag deprecated components, missing data objects, off-limits code, and other problems that need to be addressed before assigning code reviewers.
Build Your First Automation in 2 Minutes
That's it! Now sit back and watch gitStream run automation rules on your next PR.
Tip: Install gitStream for your entire organization
gitStream can be installed for one repo, specific repos, or all repos in your organization. We recommend installing for all because it will ensure all new repos are able to use gitStream. You can change this setting at any time in the future.
That's it! Now sit back and watch gitStream run automation rules on your next PR.
Coming soon
Want to report a bug, request a new feature, ask a question, get updates for new features, or propose a new configuration for the automation library? Join us on GitHub.
Learn how to integrate gitStream with Asana
Automatically label PRs that are missing references to Asana resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Asana Link
labelLabel Missing Asana
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_asana:
+ if:
+ - {{not (has.asana.ticket_in_title or has.asana.ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Asana Link"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated Asana resource.
+
+has:
+ asana:
+ ticket_in_title: {{ pr.title | includes(regex=r/asana-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/app\.asana.\com\/(\d+)\/(\d+)\/(\d+)\/(\d+)\/(\d+)/) }}
+
+colors:
+ red: 'b60205'
+
Provide automatic links to Asana cards that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Asana Card
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+provider: asana
+
+# Configure this to match your organization. It is used in tracker.asana.baseurl.
+asanaProject: 1234
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_asana:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ asana:
+ baseurl: https://app.asana.com/0/[asanaProject]/0/
+ pattern: r/asana-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Learn how to integrate gitStream with Azure Boards.
Automatically label PRs that are missing references to Azure Boards resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Azure Boards Link
labelLabel Missing Azure Boards
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_azure:
+ if:
+ - {{not (has.azure.ticket_in_title or has.azure.ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Azure Boards Link"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated resource in Azure Boards.
+
+has:
+ azure:
+ ticket_in_title: {{ pr.title | includes(regex=r/(\w+)-(\w+)-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/(dev\.azure\.com|(\w+)\.visualstudio\.com)\/(\w+)\/(\w+)\/_workitems\/edit\/(\d+)/) }}
+
+colors:
+ red: 'b60205'
+
Provide automatic links to Azure Boards resources that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Azure Boards Resource
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Configure these to match your organization.
+provider: azure
+# The name of your Azure organization
+orgName: org
+# The name of your Azure project
+azureProject: my_project
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_azure_boards:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ azure:
+ baseurl: https://dev.azure.com/[orgName]/[azureProject]/_workitems/
+ pattern: r/(\w+)-(\w+)-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Approve PRs from Dependabot
Conditions (all must be true):
Automation Actions:
approved-dependabot
label to the PRApprove Dependabot
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_dependabot:
+ if:
+ - {{ branch.name | includes(term="dependabot") }}
+ - {{ branch.author | includes(term="dependabot") }}
+ run:
+ - action: approve@v1
+ - action: add-label@v1
+ args:
+ label: "approved-dependabot"
+ - action: merge@v1
+ args:
+ wait_for_all_checks: true
+ squash_on_merge: true
+
Automatically trigger GitHub Actions based on PR content like changed resources, source or target branch, slash commands, and more.
Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions by Branch
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+automations:
+ {% for item in pipelines %}
+ # Change pr.target to branch.name if you want to trigger on the source branch rather then the target branch.
+ dispatch_github_action_{{ item.name }}:
+ if:
+ - {{ pr.target | includes(term=item.branch_prefix) }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ workflow: .github/workflows/{{ item.workflow }}
+ check_name: {{ item.name }}
+ - action: add-label@v1
+ args:
+ label: {{ item.label }}
+ {% endfor %}
+
+
+pipelines:
+ - name: mobile_ci
+ label: Mobile CI
+ branch_prefix: 'mobile-'
+ workflow: mobile.yml
+ - name: backend_ci
+ label: Backend CI
+ branch_prefix: 'backend-'
+ workflow: 'backend.yml'
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Using Labels
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - label_added
+ - label_removed
+
+automations:
+ {% for item in pipelines %}
+ dispatch_github_action_{{ item.name }}:
+ if:
+ - {{ pr.labels | match(term=item.label) | some }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ workflow: .github/workflows/{{ item.workflow }}
+ check_name: {{ item.name }}
+ {% endfor %}
+
+pipelines:
+ - name: mobile-ci
+ label: Mobile CI
+ workflow: mobile.yml
+ - name: backend-ci
+ label: Backend CI
+ workflow: 'backend.yml'
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+automations:
+ {% for item in pipelines %}
+ dispatch_github_action_{{ item.name }}:
+ if:
+ - {{ files | match(list=item.resources) | some }}
+ run:
+ - action: run-github-workflow@v1
+ args:
+ workflow: .github/workflows/{{ item.workflow }}
+ check_name: {{ item.name }}
+ - action: add-label@v1
+ args:
+ label: {{ item.label }}
+ {% endfor %}
+
+
+pipelines:
+ - name: mobile-ci
+ label: Mobile CI
+ resources:
+ - 'src/android/'
+ - 'src/ios/'
+ workflow: mobile.yml
+ - name: backend-ci
+ label: Backend CI
+ resources:
+ - 'src/api/'
+ - 'src/services'
+ workflow: 'backend.yml'
+ - name: frontend-ci
+ label: Frontend CI
+ resources:
+ - 'src/app/'
+ workflow: 'frontend.yml'
+
Automatically skip GitHub Actions based on branch names, modified resource, slash commands, and more.
Prerequisite Config for Required Statuses
If you want to skip a required status check, you will need to make sure that your branch protection is configured to allow gitStream to bypass status check requirements.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions by Branch
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+# Optionally, you can change pr.target to branch.name
+# if you want to trigger based on the source branch name rather then the target branch name.
+automations:
+ skip_github_action_branch:
+ if:
+ - {{ pr.target | includes(term='release') }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: staging-ci
+ conclusion: skipped
+ - action: add-comment@v1
+ args:
+ comment: |
+ [gitStream](https://docs.gitstream.cm) automatically skipped staging CI pipelines because this PR targets the release branch.
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Use Labels to Automatically Skip GitHub Actions
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - label_added
+ - label_removed
+
+automations:
+ skip_github_action_label:
+ if:
+ - {{ pr.labels | match(term='experimental') | some }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: production-ci
+ conclusion: skipped
+ - action: add-comment@v1
+ args:
+ comment: |
+ [gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this is labeled for experimental release.
+
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+ - commit
+
+automations:
+ skip_github_action_resource:
+ if:
+ - {{ files | match(term='docs/') | every }}
+ run:
+ - action: add-github-check@v1
+ args:
+ check_name: release-ci
+ conclusion: skipped
+ - action: add-github-check@v1
+ args:
+ check_name: mobile-ci
+ conclusion: skipped
+ - action: add-comment@v1
+ args:
+ comment: |
+ [gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this PR only contains docs changes.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Automatically apply labels to PRs that are assisted by GitHub Copilot. You can apply labels based on a known list of Copilot users, PR tags, or by prompting the PR author to indicate if they used Copilot.
Automatically apply labels to PRs that are created by known users of generative AI coding tools.
Configuration Description
Conditions:
Automation Actions:
🤖 Copilot
label to the PRLabel by Contributors
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_genai:
+ # For all PRs authored by someone who is specified in the genai_contributors list
+ if:
+ - {{ pr.author | match(list=genai_contributors) | some }}
+ # Apply a label indicating the user has adopted Copilot
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
+genai_contributors:
+ - username1
+ - username2
+ - etc
+
Look for a specific tag in the PR title, description, comments or commit messages and if found add a label to the PR
Configuration Description
Conditions:
#copilot#
tag is found in any of the PR title, description, comments or commit messages for commits in the PRAutomation Actions:
🤖 Copilot
label to the PRLabel Copilot by Tag
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_copilot:
+ # Detect PRs that contain the text '#copilot#' in the title, description, comments, or commit messages
+ if:
+ - {{ copilot_tag.pr_title or copilot_tag.pr_desc or copilot_tag.pr_comments or copilot_tag.commit_messages }}
+ # Apply a label indicating the user has adopted Copilot
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
+copilot_tag:
+ pr_title: {{ pr.title | includes(regex=r/#copilot#/) }}
+ pr_desc: {{pr.description | includes(regex=r/#copilot#/) }}
+ pr_comments: {{ pr.comments | map(attr='content') | match(regex=r/#copilot#/) | some }}
+ commit_messages: {{ branch.commits.messages | match(regex=r/#copilot#/) | some }}
+
Prompt PR authors to indicate if they used Copilot for the PR and automatically label the PR if they did. This requires two separate automation files to handle posting the prompt and labeling accordingly.
Configuration Description
Conditions:
Automation Actions:
Ask the PR author about Copilot usage.
-*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+
+automations:
+ comment_copilot_prompt:
+ # Post a comment for all PRs to prompt the PR author to indicate whether they used Copilot to assist coding in this PR
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Please mark whether you used Copilot to assist coding in this PR
+
+ - [ ] Copilot Assisted
+ - [ ] Not Copilot Assisted
+
Configuration Description
Conditions:
Automation Actions:
🤖 Copilot
label to the PR Label PRs where the user indicated Copilot usage
-*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - comment_added
+ - commit
+ - merge
+
+automations:
+ # You should use this automation in conjunction with comment_copilot_prompt.cm
+ label_copilot_pr:
+ # If the PR author has indicated that they used Copilot to assist coding in this PR,
+ # apply a label indicating the PR was supported by Copilot
+ if:
+ - {{ pr.comments | filter(attr='commenter', term='gitstream-cm') | filter (attr='content', regex=r/\- \[x\] Copilot Assisted/) | some}}
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Approve PRs that only contain changes to Godoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
📓 Godoc Only
labelReview Godoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ #Assign PRs that only affect godocs to the technical writing team and add docs label
+ review_godoc:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/^\/\/.*/) | every }}
+ - {{ files | extensions | match(regex=r/go/) | every }}
+
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓godoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [org/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
Require Godoc for all new Golang classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Godoc
label.Enforce Godoc for New Golang Classes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_godoc_new_class:
+ if:
+ - {{ is.go and is.new }}
+ - {{ source.diff.files | match(attr='diff', regex=r/\/*[\s\S]*?\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing godoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ godoc is required for all Golang classes. Please add godoc to all new classes in this PR.
+
+is:
+ go: {{ files | extensions | match(regex=r/go/) | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Require more extensive reviews for large Golang changes that lack Godoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.⚠️ Missing Godoc
LabelReview Godoc
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ #Require more extensive reviews for large Golang changes that lack Godoc updates.
+ review_godoc_large:
+ if:
+ - {{ changes.additions > 100}}
+ - {{ source.diff.files | matchDiffLines(regex=r/^\/\/.*/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Godoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to Golang classes, but is missing updates to Godoc. Please double check for any necessary Godoc updates.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+
+colors:
+ yellow: 'fbca04'
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Special thanks to Boemo W Mmopelwa for providing these examples.
Special thanks to Boemo W Mmopelwa for providing these examples.
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Special thanks to Boemo W Mmopelwa for providing these examples.
Javadoc Examples:
Unblock PRs that only change Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
org/tech-writers
team for optional review. 📓 Javadoc Only
labelReview Javadoc Changes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ # Assign PRs that only affect JavaDocs to the technical writing team and add docs label
+ review_javadoc:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | every }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\b(public|protected|private|static|final|synchronized)?\s+\w+\s+\w+\s*\(([^)]*)\)\s*\{/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓 Javadoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [org/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
If a PR modifies the input parameters for a Java method, but not the associated Javadocs, notify reviewers to check for Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Javadoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_javadoc_input_parameters:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/\*\s@param/) | nope }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\b(public|protected|private|static|final|synchronized)?\s+\w+\s+\w+\s*\(([^)]*)\)\s*\{/) | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR modifies method input parameters, but is missing Javadoc changes. Please check to ensure no Javadoc changes are necessary.
+
Require more extensive reviews for large Java changes that lack Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/tech-writers
team.⚠️ Missing Javadoc
LabelReview Javadoc for Large Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ #Require more extensive reviews for large Java changes that lack Javadoc updates.
+ review_javadoc_large:
+ if:
+ - {{ changes.ratio > 25}}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Javadoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ # Sum all the line removed in the PR
+ deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
+ # Calculate the ratio of new code
+ ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}
+
+colors:
+ yellow: 'fbca04'
+
Automatically request changes when someone creates a new Java class that lacks Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Javadoc
label.Review Javadoc Requirements for New Classes
manifest:
+ version: 1.0
+
+automations:
+ review_new_class_javadoc:
+ # Triggered for new Java files that lack Javadoc content.
+ if:
+ - {{ is.java and is.new }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Javadoc"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ This PR creates new Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.
+
+is:
+ java: {{ files | extensions | match(term='java') | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Special thanks to Boemo W Mmopelwa for providing these examples.
Special thanks to Boemo W Mmopelwa for providing these examples.
Learn how to integrate gitStream with Jira
Label PRs that don't reference a Jira ticket in the title or description. This uses regex to detect Jira ticket formats in the title (e.g. ABC-1234), and URLs to Jira tickets in the description.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-jira
label.Label Missing Jira Info
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_jira_info:
+ # Triggered for PRs that don't have either a Jira ticket number in the title,
+ # or a link to a Jira ticket in the PR description.
+ if:
+ - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "missing-jira"
+ color: 'F6443B'
+
+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}/) }}
+
Provide automatic links to Jira issues that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Jira Card
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+provider: jira
+
+# Change this to the name of your Jira organization
+orgName: org
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_jira:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ jira:
+ baseurl: https://[orgName].atlassian.net/browse/
+ pattern: r/\b[A-Za-z]+-\d+\b/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Included with gitStream Core Functionality
This integration is part of gitStream core functionality, and requires no additional configuration.
Jit Examples:
Manage review assignment for high and medium risk Jit security alerts.
Configuration Description
Review Jit High Alerts
Review Jit Medium Alerts
Review Jit Security Alerts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_jit_high_alerts:
+ if:
+ - {{ jit.metrics.HIGH > 0 }}
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [my-organization/security-team]
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR requires additional review because Jit reported one or more high risk vulnerabilities.
+ review_jit_medium_alerts:
+ if:
+ - {{ jit.metrics.MEDIUM > 0 }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR requires additional reviewers because Jit reported one or more medium risk vulnerabilities.
+
+
+jit: {{ pr | extractJitFindings }}
+
Close PRs where Jit detects a secret and post a comment explaining steps to remedy the situation.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Security Control
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_jit_secret:
+ if:
+ - true
+ - {{ jit.vulnerabilities | match(attr='security_control', term='Secret Detection') | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Jit detects secrets in this PR. Please complete the following steps:
+ 1. Undo the commit with git reset and remove all secrets from the files you modified.
+ 2. Deactivate the secret in any locations its used and replace it with a new key
+ 3. Commit your changes and resubmit your PR.
+ - action: close@v1
+
+
+jit: {{ pr | extractJitFindings }}
+
Label the number of high, medium, and low risk vulnerabilities Jit reports for PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Jit Alerts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in reports %}
+ label_jit_{{ item.name }}:
+ if:
+ - {{ item.count > 0}}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'Jit: {{ item.count }} {{ item.name }} vulnerabilities'
+ color: {{ colors.red if (item.name == 'high') else (colors.orange if (item.name == 'medium' ) else colors.yellow) }}
+ {% endfor %}
+
+jit: {{ pr | extractJitFindings }}
+
+reports:
+ - name: high
+ count: {{ jit.metrics.HIGH }}
+ - name: medium
+ count: {{ jit.metrics.MEDIUM }}
+ - name: low
+ count: {{ jit.metrics.LOW }}
+
+colors:
+ red: 'b60205'
+ orange: 'd93f0b'
+ yellow: 'fbca04'
+
Notify your Security team when someone ignores a Jit vulnerability report and accepts the risk.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Ignore and Accept
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_jit_ignore_accept:
+ if:
+ - {{ pr.conversations | reject(attr='commenter', term='jit-ci') | filter(attr='content', term='#jit_ignore_accept') | some }}
+ run:
+
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my-organziation/security]
+ - action: add-label@v1
+ args:
+ label: '❕ Jit: Ignore - Accept Risk'
+ - action: add-comment@v1
+ args:
+ comment: |
+ The security team has been assigned for optional review because this PR ignores a Jit alert and accepts the associated risks.
+
+jit: {{ pr | extractJitFindings }}
+
JSDoc Examples:
Approve PRs that only contain changes to JSDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.📓 JSDoc Only label
Review JSDoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ #Assign PRs that only affect JSDocs to the technical writing team and add docs label
+ review_jsdoc:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/\/*\*[\s\S]*?\//) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓JSDoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
Warn PR authors when they change JavaScript function or constructor input parameters without updating JSDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JSDoc Input Parameters
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_jsdoc_input:
+ if:
+ - {{ source.diff.files | matchDiffLines(regex=r/.*\s@param/) | nope }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\((?:.*\:.*\))/) | some }}
+
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR appears to modify method input parameters, but is missing JSDoc changes. Please check to ensure no JSDoc changes are necessary.
+
Require more extensive reviews for large JavaScript changes that lack JSDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.⚠️ Missing JSDoc
LabelReview JSDoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ #Require more extensive reviews for large Javascript changes that lack JSDoc updates.
+ review_jsdoc_large:
+ if:
+ - {{ changes.ratio > 25}}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ No JSDoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to JavaScript classes, but is missing updates to JSDoc. Please double check for any necessary JSDoc updates.
+
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+ # Sum all the line removed in the PR
+ deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
+ # Calculate the ratio of new code
+ ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}
+
+colors:
+ yellow: 'fbca04'
+
Require JSDoc for all new JavaScript classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing JSDoc
label.Enforce JSDoc for New JavaScript Classes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_jsdoc_new_class:
+ if:
+ - {{ is.javascript and is.new }}
+ - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing JSDoc"
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ JSDoc is required for all JavaScript classes. Please add JSDoc to all new classes in this PR.
+
+is:
+ javascript: {{ files | extensions | match(list=['js', 'ts']) | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Special thanks to Boemo W Mmopelwa for help with these examples.
LinearB is a software delivery management platform that makes it easy to benchmark your engineering organization, track engineering metrics and identify opportunities for improvement.
These examples show how to label PRs that are assisted by GitHub Copilot so you can easily track productivity within LinearB. These examples can be adapted for any other generative AI solutions you might use.
Automatically apply labels to PRs that are assisted by GitHub Copilot. You can apply labels based on a known list of Copilot users, PR tags, or by prompting the PR author to indicate if they used Copilot.
Automatically apply labels to PRs that are created by known users of generative AI coding tools.
Configuration Description
Conditions:
Automation Actions:
🤖 Copilot
label to the PRLabel by Contributors
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_genai:
+ # For all PRs authored by someone who is specified in the genai_contributors list
+ if:
+ - {{ pr.author | match(list=genai_contributors) | some }}
+ # Apply a label indicating the user has adopted Copilot
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
+genai_contributors:
+ - username1
+ - username2
+ - etc
+
Look for a specific tag in the PR title, description, comments or commit messages and if found add a label to the PR
Configuration Description
Conditions:
#copilot#
tag is found in any of the PR title, description, comments or commit messages for commits in the PRAutomation Actions:
🤖 Copilot
label to the PRLabel Copilot by Tag
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_copilot:
+ # Detect PRs that contain the text '#copilot#' in the title, description, comments, or commit messages
+ if:
+ - {{ copilot_tag.pr_title or copilot_tag.pr_desc or copilot_tag.pr_comments or copilot_tag.commit_messages }}
+ # Apply a label indicating the user has adopted Copilot
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
+copilot_tag:
+ pr_title: {{ pr.title | includes(regex=r/#copilot#/) }}
+ pr_desc: {{pr.description | includes(regex=r/#copilot#/) }}
+ pr_comments: {{ pr.comments | map(attr='content') | match(regex=r/#copilot#/) | some }}
+ commit_messages: {{ branch.commits.messages | match(regex=r/#copilot#/) | some }}
+
Prompt PR authors to indicate if they used Copilot for the PR and automatically label the PR if they did. This requires two separate automation files to handle posting the prompt and labeling accordingly.
Configuration Description
Conditions:
Automation Actions:
Ask the PR author about Copilot usage.
-*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - pr_created
+
+automations:
+ comment_copilot_prompt:
+ # Post a comment for all PRs to prompt the PR author to indicate whether they used Copilot to assist coding in this PR
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ Please mark whether you used Copilot to assist coding in this PR
+
+ - [ ] Copilot Assisted
+ - [ ] Not Copilot Assisted
+
Configuration Description
Conditions:
Automation Actions:
🤖 Copilot
label to the PR Label PRs where the user indicated Copilot usage
-*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+on:
+ - comment_added
+ - commit
+ - merge
+
+automations:
+ # You should use this automation in conjunction with comment_copilot_prompt.cm
+ label_copilot_pr:
+ # If the PR author has indicated that they used Copilot to assist coding in this PR,
+ # apply a label indicating the PR was supported by Copilot
+ if:
+ - {{ pr.comments | filter(attr='commenter', term='gitstream-cm') | filter (attr='content', regex=r/\- \[x\] Copilot Assisted/) | some}}
+ run:
+ - action: add-label@v1
+ args:
+ label: '🤖 Copilot'
+
These examples show how to label PRs based on the changed code so you can more easily compare metrics across languages, frameworks, changed directories, and more.
Automatically label PRs to indicate what resources are being changed.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Modified Resources
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_resource_{{ item.name }}:
+ if:
+ -{{ branch.name | includes(regex=item.branch) or files | match(list=item.resources) }}
+ run:
+ - action: add-label@v1
+ args:
+ label: {{ item.name }}
+ {% endfor %}
+
+labels:
+ - name: Core
+ resources:
+ - src/app
+ branch: r/^core-/
+ - name: mobile
+ resources:
+ - src/android
+ - src/ios
+ branch: r/^mobile-/
+
Automatically detect which programming languages are contained in PRs and automatically label the PRs appropriately.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label PRs by Language
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in labels %}
+ label_{{ item.name }}_pr:
+ if:
+ - {{ files | match(regex=item.resources) | some }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.name }}'
+ {% endfor %}
+
+labels:
+ - name: Java
+ resources: r/.java$/
+ - name: Rust
+ resources: r/.rs$/
+ - name: HTML
+ resources: r/.html$/
+ - name: JavaScript
+ resources: r/.js$/
+ - name: Python
+ resources: r/.py$/
+ - name: Golang
+ resources: r/.go$/
+ - name: Ruby
+ resources: r/.rb$/
+ - name: CSS
+ resources: r/.css/
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Integrate gitStream with RDoc: a documentation generation framework for Ruby.
Approve PRs that only contain changes to RDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
📓 RDoc Only
labelReview RDoc
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_rdoc:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/^[\s\t]*#.*/) | every }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "📓RDoc Only"
+ color: {{ colors.green }}
+ - action: add-reviewers@v1
+ args:
+ reviewers: [org/tech-writers]
+ - action: approve@v1
+
+colors:
+ green: '0e8a16'
+
Require RDoc for all new Ruby classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing RDoc
label.Enforce RDoc for New Ruby Classes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_rdoc_new_class:
+ if:
+ - {{ is.rb and is.new }}
+ - {{ source.diff.files | match(attr='diff', regex=r/(\#.*\n.*)*def/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing RDoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ RDoc is required for all Ruby classes. Please add documentation for this PR.
+
+is:
+ rb: {{ files | extensions | match(regex=r/rb/) | every }}
+ new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}
+
+colors:
+ yellow: 'fbca04'
+
Require more extensive reviews for large Ruby changes that lack RDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.⚠️ Missing RDoc
LabelReview RDoc
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ #Require more extensive reviews for large Ruby changes that lack RDoc updates.
+ review_rdoc_large:
+ if:
+ - {{ changes.additions > 150}}
+ - {{ source.diff.files | matchDiffLines(regex=r/(\#.*\n.*)*def/) | nope }}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing RDoc"
+ color: {{ colors.yellow }}
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR makes major changes to Ruby methods, but is missing updates to RDoc. Please double check for any necessary RDoc updates.
+ - action: add-reviewers@v1
+ args:
+ reviewers: [fourth-organization/tech-writers]
+
+changes:
+ # Sum all the lines added/edited in the PR
+ additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
+
+
+colors:
+ yellow: 'fbca04'
+
Warn PR authors when they change Ruby function or constructor input parameters without updating RDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review RDoc Input Parameters
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ review_rdoc_input:
+ if:
+ - {{ source.diff.files | match(attr='diff', regex=r/(\#.*\n.*)*def/) | nope }}
+ - {{ source.diff.files | match(attr='diff', regex=r/def.*\(.*\)/ | some }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR modifies method input parameters, but is missing RDoc changes. Please check to ensure no RDoc changes are necessary.
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
Request changes for a PR that contains a TODO statement.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review TODO Comments
Special thanks to Boemo W Mmopelwa for providing these examples.
Special thanks to Boemo W Mmopelwa for providing these examples.
Learn how to integrate gitStream with Shortcut
Automatically label PRs that are missing references to Shortcut resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
⚠️ Missing Shortcut Link
labelLabel Missing Shortcut
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ label_missing_shortcut:
+ if:
+ - {{not (has.shortcut.ticket_in_title or has.shortcut.ticket_in_desc)}}
+ run:
+ - action: add-label@v1
+ args:
+ label: "⚠️ Missing Shortcut Link"
+ color: {{ colors.red }}
+ - action: add-comment@v1
+ args:
+ comment: Please provide a link to the associated Shortcut resource.
+
+has:
+ shortcut:
+ ticket_in_title: {{ pr.title | includes(regex=r/(\w+)\/sc-(\d+)/) }}
+ ticket_in_desc: {{ pr.description | includes(regex=r/(app\.shortcut\.com)\/(\w+)\/story\/(\d+)\/(\w+)/) }}
+
+colors:
+ red: 'b60205'
+
Provide automatic links to Shortcut tasks that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Shortcut Task
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Configure these to match your organization.
+provider: jira
+
+# Change this to match the name of your Shortcut organization. This is used in tracker.shortcut.baseurl
+orgName: org
+
+{% set ticketid = "" %}
+{% for ticket in tickets %}
+{% if (ticket | includes(regex=r/.+/)) %}
+{% set ticketid = ticket %}
+{% endif %}
+{% endfor %}
+
+automations:
+ link_shortcut:
+ if:
+ - {{ has.ticket_in_title or has.ticket_in_branch }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})
+
+has:
+ ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
+ ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}
+
+tracker:
+ shortcut:
+ baseurl: https://app.shortcut.com/[orgName]/story/
+ pattern: r/(\w+)\/sc-(\d+)/
+
+tickets:
+ - {{branch.name | capture(regex=tracker[provider].pattern)}}
+ - {{pr.title | capture(regex=tracker[provider].pattern)}}
+
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Included with gitStream Core Functionality
This integration is part of gitStream core functionality, and requires no additional configuration.
SonarCloud Examples:
Approve PRs that pass SonarCloud's quality gate.
Configuration Description
Conditions (all must be true):
Automation Actions:
Sonar: Clean Code
label to the PR.Aprove Sonar Clean Code
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+automations:
+ approve_sonar_clean_code:
+ if:
+ - {{ sonar.bugs.rating == 'A' }}
+ - {{ sonar.code_smells.rating == 'A' }}
+ - {{ sonar.vulnerabilities.rating == 'A' }}
+ - {{ sonar.security_hotspots.rating == 'A' }}
+ - {{ sonar.duplications == null or sonar.duplications == 0 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: '✅ Sonar: Clean Code'
+ color: {{ colors.green }}
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR passes the SonarCloud quality gate check and as been automatically approved.
+
+sonar: {{ pr | extractSonarFindings }}
+
+colors:
+ green: '0e8a16'
+
Label the number of bugs, vulnerabilities, security hotspots, and code smells reported by SonarCloud.
Configuration Description
Conditions (all must be true):
extractSonarFindings
filter functionAutomation Actions:
Label SonarCloud Quality Reports
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ {% for item in reports %}
+ label_sonar_{{ item.name }}:
+ if:
+ - {{ item.count > 0}}
+ run:
+ - action: add-label@v1
+ args:
+ label: '{{ item.icon }} sonar:{{ item.name }}-{{ item.rating }}'
+ color: {{ colors.red if (item.rating == 'E' or item.rating == 'D') else (colors.orange if (item.rating == 'C' ) else colors.yellow) }}
+ {% endfor %}
+
+sonar: {{ pr | extractSonarFindings }}
+
+reports:
+ - name: vulnerabilities
+ count: {{ sonar.vulnerabilities.count }}
+ icon: 🔓
+ rating: {{ sonar.vulnerabilities.rating }}
+ - name: code smells
+ count: {{ sonar.code_smells.count }}
+ icon: ☣️
+ rating: {{ sonar.code_smells.rating }}
+ - name: security hotspots
+ count: {{ sonar.security_hotspots.count }}
+ icon: 🛡️
+ rating: {{ sonar.security_hotspots.rating }}
+ - name: bugs
+ count: {{ sonar.bugs.count }}
+ icon: 🪲
+ rating: {{ sonar.bugs.rating }}
+
+colors:
+ red: 'b60205'
+ orange: 'd93f0b'
+ yellow: 'fbca04'
+
Request changes when Sonar reports an excessive level of duplicated code.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Sonar Duplications
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+automations:
+ review_sonar_duplications:
+ if:
+ - {{ sonar.duplications > 3 }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'Sonar: {{ sonar.duplications}}% duplication'
+ color: {{ colors.yellow }}
+ - action: request-changes@v1
+ args:
+ comment: |
+ Sonar reports an excessive level of code duplication. Please consider refactoring your PR to reduce duplications.
+
+sonar: {{ pr | extractSonarFindings }}
+
+colors:
+ yellow: 'fbca04'
+
Require additional reviews for Sonar security alerts. gitStream will remove this requirement if the alerts are resolved.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/security-team
team. Customize this to match your organization.Review Sonar Alerts
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+automations:
+ review_sonar_alerts:
+ if:
+ - {{ sonar.code_smells.rating != 'A' or sonar.vulnerabilities.rating != 'A' or sonar.security_hotspots.rating != 'A'}}
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [my-organization/security-team]
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR requires additional review because it fails to meet SonarCloud clean code standards.
+
+sonar: {{ pr | extractSonarFindings }}
+
Approve changes that only affect Swimm documentation.
Configuration Description
Conditions (all must be true):
.swm
extension.Automation Actions:
swimm-docs-only
labelApprove Swimm Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ approve_swimm_changes:
+ # Triggered for any changes to Swimm documentation
+ if:
+ - {{ branch.diff.files_metadata | match(attr='file', regex=r/\.swm\//) | every }}
+ # Apply a swimm-docs-only label, approve the PR and explain why in a comment.
+ run:
+ - action: add-label@v1
+ args:
+ label: 'swimm-docs-only'
+ - action: approve@v1
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR is considered a safe change as it only affects Swimm Docs.
+ It has been automatically approved.
+
Special thanks to Omerr for providing this example.
Terraform Examples:
Automatically assign org/infrastructure
team for reviewing changes when PR contains Terraform file changes.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_terraform:
+ # Triggered for any changes to Terraform files
+ if:
+ - {{ files | match(regex=r/.*\.tf.*/) | some }}
+ # Assign infrastructure team as reviewer for change in Terraform files
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [org/infrastructure]
+ - action: add-comment@v1
+ args:
+ comment: |
+ This PR affects Terraform configurations and requires a review from the Infra team.
+
Request changes if a PR that creates a new Terraform module which do not conform to the required directory structure.
Configuration Description
Conditions (all must be true):
/modules
directory.Automation Actions:
⚠️ Missing Terraform Components
Review New Module
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+{% set misslist = [] %}
+{% for pattern in terraform %}
+{% if (newfilesinpr | match(term=pattern) | nope) %}
+{% set misslist = misslist + [pattern+' '] %}
+{% endif %}
+{% endfor %}
+
+automations:
+ review_new_terraform_module:
+ if:
+ - {{misslist | match(regex=r/.*/) | some}}
+ - {{is.mainfile and is.mainfilenotinroot }}
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ New terraform modules must contain all required components before merging. Please update your PR with the required components and gitStream will automatically remove this comment once completed.
+
+ Here are the required components, {{misslist}} should be customized appropriately:
+ my_module/
+ ├── main.tf
+ ├── outputs.tf
+ ├── providers.tf
+ - action: add-label@v1
+ args:
+ label: '⚠️ Missing Terraform Components'
+ color: '#FFA500'
+
+resources:
+ module_directory: 'modules'
+terraform:
+ - main.tf
+ - outputs.tf
+ - providers.tf
+is:
+ mainfile: {{newfilesinpr | match(term = "main.tf") | some}}
+ mainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = "main.tf") | nope }}
+newfilesinpr:
+ {{ branch.diff.files_metadata | map(attr='new_file')}}
+
Ensure that all Terraform modules imported via a source URL specify a version.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+automations:
+ review_terraform_source_version:
+ # Check if New Content contains a source URL, the URL is not part of allow list and lacks version reference
+ if:
+ - {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\".*(http|https).*\"/) | some }}
+ - {{ source.diff.files | match(attr='new_content', list=allowlist) | nope }}
+ - {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\?ref=v.*/) | nope }}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ You must reference a specific version when accessing Terraform module sources via URL, e.g. `?ref=v1.0.0`. Please update your Terraform files to follow this practice.
+
+allowlist:
+ - 'https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git'
+ - 'https://github.com/terraform-aws-modules/terraform-aws-vpc.git'
+ - 'https://github.com/terraform-aws-modules/terraform-aws-eks.git'
+
Request changes if a PR creates a new Terraform module that is missing a required prefix or keyword in the name.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Module Name
# -*- mode: yaml -*-
+
+manifest:
+ version: 1.0
+
+# Prefix Check Logic
+{% set prefixcheck = [] %}
+{% for pattern in terraform.prefixes %}
+{% if(newfilesinpr | match(term=module_location + pattern) | some) %}
+{% set prefixcheck = prefixcheck + [true]%}
+{% else %}
+{% set prefixcheck = prefixcheck + [false] %}
+{% endif %}
+{% endfor %}
+
+automations:
+ review_new_terraform_module:
+ if:
+ - {{is.mainfile and is.mainfilenotinroot}}
+ - {{module_name_checks.prefix or module_name_checks.keyword}}
+ run:
+ - action: request-changes@v1
+ args:
+ comment: |
+ Terraform module names must contain a required prefix and keyword:
+ * Prefixes: {{ terraform.prefixes }}
+ * Keywords: {{ terraform.keywords }}
+
+module_name_checks:
+ prefix: {{prefixcheck | match(term='true') | nope}}
+ keyword: {{newfilesinpr | match(list=terraform.keywords) | nope}}
+
+module_location: infrastructure/modules/
+terraform:
+ prefixes: ['aws', 'gcp', 'azure']
+ keywords: ['db', 'networking', 'security']
+
+is:
+ mainfile: {{newfilesinpr | match(term = "main.tf") | some}}
+ mainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = "main.tf") | nope }}
+newfilesinpr:
+ {{ branch.diff.files_metadata | map(attr='new_file')}}
+
gitStream enables you to build JavaScript plugins to extend functionality for more advanced data processing and pulling data from external APIs. Use gitStream plugins to seamlessly create and integrate custom filters and other capabilities within your gitStream automations.
Example: isFlaggedUser
Here is an example of a filter function plugin that evaluates a username input against a list of specified usernames and returns true if the user is in the list.
const flaggedUsers = ["user1", "user2"];
+
+function isFlaggedUser(username) {
+ if (flaggedUsers.includes(username)) {
+ return true;
+ } else {
+ return false;
+ }
+};
+
+module.exports = isFlaggedUser;
+
isFlaggedUser
filter function that can be invoked inside gitStream CM files. For example, you can use this to enable gitStream automations to trigger only for specific PR authors. gitStream plugins can be installed for an entire git organization or for individual repos.
Repository Plugins Take Precedence
If two filter function plugins have the same name, the repository-level plugin overrides the organization-level plugin.
To use a filter function plugin in all your repositories, place it inside your cm
repository in the following location:
plugins/filters/<filterName>/index.js
To use a filter function plugin for a single repository, place it inside the repo in the following location:
.cm/plugins/filters/<filterName>/index.js
gitStream Community Plugins
We maintain an official list of community-contributed gitStream plugins. Click here to explore plugin examples.
Once installed, you can call your new plugins inside CM files using the same conventions as the built in filter functions. Filters are called with a pipe operator (|
) and can take arguments. The first argument must be declared before the pipe, and all remaining arguments are passed as a set inside parenthesis. For example:
gitStream plugins are based on the CommonJS module standard, a widely used pattern for structuring and importing JavaScript modules.
Supported JavaScript Dependencies
gitStream supports the following JavaScript dependencies: axios, github actions core (@actions/core), moment, lodash, octokit rest api (@octokit/rest)
No other dependencies are supported at this time. If you have recommendations for new dependencies, please open a new issue on the gitStream GitHub repo.
Each filter function plugin must have its own unique directory inside the appropriate /filters
directory for your repo or organization. To create a new filter function, create an index.js file inside the plugin's top-level directory, all plugins must have an index.js file that serves as the primary entry point
One of the functions contained inside this file must be exported via module.exports
, using the following conventions:
Export plugins that use synchronous code:
When using async JavaScript in your plugin, you need two things:
callback()
containing any errors as the first argument and the result of the filter as the second.module.exports
statement that includes the properties async: true
and filter: <filterName>
with <filterName>
matching the primary function that's being exported.const myFilter = async (author, callback) => {
+ const message = { text: "Hello ${author}!" };
+ const error = null;
+ return callback(error, message.text);
+};
+
+module.exports = {
+ async: true,
+ filter: myFilter
+}
+
Async Error Handling
Errors reported by async plugins are output to the workflow runner logs. E.g. GitHub Actions, GitLab CI, etc.
Here's how to invoke the new filter from this example:
automations:
+ welcome_author:
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: {{ pr.author | myFilter }}
+
Debugging with console.log()
Data passed to console.log()
is output in your workflow runner logs, e.g. GitHub Actions, GitLab CI, etc.
15 Minute Time Limit
gitStream actions are terminated after 15 minutes, this is a hard limit that can't be extended.
Filter function plugins can accept any number of arguments. The first argument must be passed to the filter function via a |
operator; all subsequent arguments are passed as a set inside parenthesis.
Filter function to combine two strings
This example accepts two strings and combines them, separating by a space:
function combineStrings(str1, str2) {
+ return str1 + " " + str2;
+}
+module.exports = combineStrings;
+
In the following invocation, "Hello" is passed as str1
and "world!" is passed as str2
{{ "Hello" | combineStrings("world!") }}
Check out the community plugin library.
Check out the filter function plugin library to explore plugins created by the LinearB community.
LinearB maintains a collection of community-contributed gitStream plugins. Here are the instructions for publishing a plugin as part of this library.
Create a directory for your plugin inside one of the subdirectories in plugins/filters
. The name of the directory must match the name of the exported JavaScript function. Then ensure you have all of the required files and JSDoc content outlined below.
Here is an example of a well-designed gitStream plugin.
Required Files:
module.exports
that is documented according to the JSDoc requirements outlined below.jsdoc2md
, see the instructions below.Required JSDoc tags:
@module
- This must match the name of the exported JavaScript function.@description
- A 1-2 line description that wholistically describes the functionality of the plugin.@param
- There should be one @param
tag for each argument the plugin accepts, with indicated types. Indicate which parameter is the default input parameter with the name "Input."@returns
- Provide the type and a short description.@example
- Simple examples that show how to invoke the plugin.@license
- The name of the lincense contained in the LICENSE file. Here is an example of properly formatted JSDoc content:
/**
+ * @module isFlaggedUser
+ * @description Returns true if the username that is passed to this function is specified in a predefined list of users.
+ * This is useful if you want gitStream automations to run only for specified users.
+ * @param {string} Input - The GitHub username to check.
+ * @returns {boolean} Returns true if the user is specified in the flaggedUsers list, otherwise false.
+ * @example {{ pr.author | isFlaggedUser }}
+ * @license MIT
+**/
+
How to Generate Plugin Reference Markdown
You can use jsdoc2md to convert the JSDoc content of your plugin to markdown using templates we've provided. First install jsdoc2md:
npm install -g jsdoc-to-markdown
Then, invoke the following command from inside your plugin directory:
jsdoc2md --partial ../../../docs/snippets/partials/body.hbs --partial ../../../docs/snippets/partials/sig-name.hbs --files index.js > reference.md
This should output a reference.md file that contains properly formatted markdown based on the JSDoc contents of your plugin.
This article provides Continuous Merge (CM) examples to help you start customizing gitStream automations to meet the needs of your team.
Changes to documentation, testing, and code formatting are often safe enough that there is little to no risk in letting an individual contributor merge those changes without needing to distract other people on their team to meet organization-wide requirements for multiple reviews on PRs. A good first Continuous Merge (CM) automation to implement is one that labels and approves changes to resources that could be considered safe changes.
This example uses the filter functions allDocs
, allTests
, isFormattingChange
and match
to detect changes that should be safe to merge with minimal review. It then uses the add-label
automation action to apply a safe-changes label and the approve
automation action to provide an approval review.
Label and Approve Simple Changes
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ safe_changes:
+ if:
+ - {{ is.docs or is.tests or is.asset or is.formatting }}
+ run:
+ - action: add-label@v1
+ args:
+ label: 'safe-changes'
+ - action: approve@v1
+is:
+ docs: {{ files | allDocs }}
+ tests: {{ files | allTests }}
+ asset: {{ files | match(regex=r/\.(png|svg|gif|css)$/) | every }}
+ formatting: {{ source.diff.files | isFormattingChange }}
+
Test Your Automation in Dry Run Mode
gitStream includes a dry-run mode that let's you test your automations on your desired repo without pushing significant code, documentation, or other changes to the repo.
Learn more in our guide: How to Test Your Automations.
Selecting the right reviewer for your PR is crucial to ensure that your changes are thoroughly reviewed and that any issues are identified and addressed before they are merged into the main codebase.
This example uses the codeExperts
filter function to identify the most qualified contributors based on their activity in the repo. It then assigns those individuals as reviewers on the PR with the add-reviewers
automation action and posts a comment that lists the code experts via the explain-code-experts
automation action.
Identify and Assign Code Experts for Reviews
This example uses the codeExperts filter function to identify the people who have the most expertise in the relevant code, assigns them as reviewers, and provides a comment that explains how those people were selected.
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+
+automations:
+ assign_code_experts:
+ # Triggered when someone applies a suggest-reviewer label to a PR.
+ if:
+ - {{ pr.labels | match(term='suggest-reviewer') | some }}
+ run:
+ - action: add-reviewers@v1
+ args:
+ reviewers: {{ repo | codeExperts(gt=10) }}
+ - action: explain-code-experts@v1
+ args:
+ gt: 10
+
Complex and sensitive PRs often require more nuanced and complex review processes that bring in outside teams of experts to review code changes. gitStream makes it easy to set up custom review policies to keep teams align across your organization. This example contains two automations that implement custom review policies for specific parts of a codebase.
First, the security_review
automation uses the require-reviewers
automation action to add the security team from the git organization as reviewers on PRs that affect the auth
directory of the repo. This action accepts a reviewers:
argument that contains a list of teams or individual users; you will need to change this value to match your organization and users.
Second, the double_review
automation forces any changes to the agent
directory to require a review from two people using the set-required-approvals
automation action.
Enforce Review Policies
# -*- mode: yaml -*-
+manifest:
+ version: 1.0
+automations:
+ security_review:
+ if:
+ - {{ files | match(regex=r/auth\//) | some }}
+ run:
+ - action: require-reviewers@v1
+ args:
+ reviewers: [my_organization/security]
+ - action: add-reviewers@v1
+ args:
+ reviewers: [my_organization/security]
+ double_review:
+ if:
+ - {{ files | match(regex=r/agent\//) | some }}
+ run:
+ - action: set-required-approvals@v1
+ args:
+ approvals: 2
+
Take a Look at the Quickstart Examples
You're ready to browse our CM example library to build more automations for your repo. We have examples that help provide context to PRs with labels, assign reviewers based on custom criteria, manage security requirements, and more.
gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
"},{"location":"#features","title":"Features","text":"Auto-Merge PRs
Not all PRs need extensive review policies that loop in multiple experts. gitStream lets you auto-merge safe changes, small fixes, PRs from trusted teams, and anything else you want to unblock the review process to keep your team focused on their work.
Contextual Labels
Reduce the mental burden of code reviews with labels that provide a high degree of context. Indicate an estimated time to review or flag potential issues with Jira information, missing tests, deleted files, and more.
Review Assignment
Identifying the correct people to review a PR can take time, particularly for complex projects and repos requiring deep expertise. Assign code experts to review complex PRs, notify your security team about sensitive changes, and automatically assign reviewers based on the contents of the PR.
Automated Change Requests
Reduce code review noise by catching issues before anyone invests precious time. Flag deprecated components, missing data objects, off-limits code, and other problems that need to be addressed before assigning code reviewers.
Build Your First Automation in 2 Minutes
GitHub GitLab BitBucketThat's it! Now sit back and watch gitStream run automation rules on your next PR.
Tip: Install gitStream for your entire organization
gitStream can be installed for one repo, specific repos, or all repos in your organization. We recommend installing for all because it will ensure all new repos are able to use gitStream. You can change this setting at any time in the future.
That's it! Now sit back and watch gitStream run automation rules on your next PR.
Coming soon
"},{"location":"#get-involved","title":"Get Involved","text":"Want to report a bug, request a new feature, ask a question, get updates for new features, or propose a new configuration for the automation library? Join us on GitHub.
"},{"location":"automation-actions/","title":"Automation actions","text":"Actions are the end results of the automation described in your .cm
file.
Legend
The icons indicate the availability status of each action.
send-http-request
is executed immediately after the evaluation of the condition. For all other actions, gitStream executes the actions in the order they are listed per automation. If an action result fails, the following actions will not be executed.
add-comment
add-github-check
add-label
add-labels
add-reviewers
explain-code-experts
approve
close
merge
send-http-request
send-slack-message
set-required-approvals
request-changes
require-reviewers
run-github-workflow
Note
Multiple actions can be listed in a single automation. The actions are invoked one by one.
"},{"location":"automation-actions/#dynamic-actions-arguments","title":"Dynamic actions arguments","text":"Arguments values a dynamic value is supported using expressions based on Jinja2 syntax, and includes gitStream context variables, for example:
automations:\npr_complexity:\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: \"Estimated {{ branch | estimatedReviewTime }} minutes to review\"\n
"},{"location":"automation-actions/#reference","title":"Reference","text":""},{"location":"automation-actions/#add-comment","title":"add-comment
","text":"This action, once triggered, adds a comment to the PR.
This is a manged action, when a PR updates, the existing comments that were added by gitStream are re-evaluated and those that are not applicable are removed.
Args Usage Type Descriptioncomment
Required String Sets the comment, markdown is supported exampleautomations:\nsenior_review:\nif:\n- {{ files | match(term='core/') | some }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nCore service update\n(Updates API)\n
"},{"location":"automation-actions/#add-github-check","title":"add-github-check
","text":"This action, once triggered, adds a completed
check with the specified conclusion to the listed checks in the PR.
check_name
Required String The check name to be added to the checks list on gitHub conclusion
Required String The conclusion of the check. The value is one of the following: action_required
, cancelled
, timed_out
, failure
, neutral
, skipped
, success
exampleautomations:\n# Skip UI checks if the PR doesn't have a UI code changes\nskip_ui_check:\nif:\n- {{ not has.fe_code_changes }} run:\n- action: add-github-check@v1\nargs:\ncheck_name: FE-tests\nconclusion: skipped\nhas:\nfe_code_changes: {{ files | match(regex=r/frontend\\//) | some }}\n
"},{"location":"automation-actions/#add-label","title":"add-label
","text":"This action, once triggered, adds a label to the PR.
This is a manged action, when a PR updates, the existing labels that were added by gitStream are re-evaluated and those that are not applicable are removed.
Args Usage Type Descriptionlabel
Required String The label text any string can work color
Optional String The color in hex, for example: 'FEFEFE'
(you can also add #
prefix #FEFEFE
) exampleautomations:\nsenior_review:\nif:\n- {{ files | match(term='api/') | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: api-change\n
"},{"location":"automation-actions/#add-labels","title":"add-labels
","text":"This action, once triggered, adds a list of labels to the PR.
This is a manged action, when a PR updates existing labels that were added by gitStream are re-evaluated and those that are not applicable are removed.
Args Usage Type Descriptionlabels
Required [String] The list of text labels"},{"location":"automation-actions/#add-reviewers","title":"add-reviewers
","text":"This action, once triggered, sets a specific reviewer.
Args Usage Type Descriptionreviewers
Required [String] Sets required reviewers. Supports user names and teams. Teams notated by adding a prefix with the owner name e.g. owner/team
team_reviewers
Optional [String] Sets required team reviewers without a prefix team
unless_reviewers_set
Optional Bool When true
, the reviewers are not added if the PR has already assigned reviewers. It is set to false
by default fail_on_error
Optional Bool When true
, trying to assign illegal reviewers shall fail the automation, when false
these errors are silently ignored. It is set to true
by default wait_for_all_checks
Optional Boolean By default false
. When true
, the action will add reviewers only if all checks (except gitStream) are completed with neutral
, skipped
, or success
conclusion exampleautomations:\nsenior_review:\nif:\n- {{ files | match(term='src/ui/') }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [popeye, olive, acme/team-a]\n
Enable Team Write Access
If you want to assign teams as PR reviewers, you need to first make sure the team has write access to the repo in via your organization's settings. For more info, refer to the GitHub instructions for managing team review settings.
"},{"location":"automation-actions/#explain-code-experts","title":"explain-code-experts
","text":"This action, shall add a comment with codeExperts suggestion. If the comment already exists, the comment shall be edited.
Args Usage Type Descriptionlt
Optional Integer Filter the user list, keeping those below the specified threshold gt
Optional Integer Filter the user list, keeping those above the specified threshold exampleautomations:\ncode_experts:\nif:\n- true\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10\n
"},{"location":"automation-actions/#approve","title":"approve
","text":"This action, once triggered, approves the PR for merge.
This is a manged action, when a PR updates existing approval by gitStream is re-evaluated and removed if no longer applicable.
exampleautomations:\nsmall_change:\nif:\n- {{ source.diff.files | isFormattingChange }}\nrun:\n- action: approve@v1\n
"},{"location":"automation-actions/#close","title":"close
","text":"This action, once triggered, close the PR without merging.
exampleautomations:\nclose_ui_changes_by_non_ui:\nif:\n- {{ files | match(regex=r/src\\/views/) | some }}\n- {{ pr.author_teams | match(term='ui-team') | nope }}\nrun:\n- action: add-comment@v1\nargs: comment: |\nPlease contact a member of `ui-team` team if you need to make changes to files in `src/views`\n- action: close@v1\n
"},{"location":"automation-actions/#merge","title":"merge
","text":"Once triggered, merge the PR if possible. It can be set to wait for all checks to pass or only required ones.
Args Usage Type Descriptionwait_for_all_checks
Optional Boolean By default false
, so only Required checks can block merge, when true
the action will merge after all checks are completed with neutral
, skipped
, or success
conclusion (except gitStream itself) rebase_on_merge
Optional Boolean By default false
, when merging use rebase mode squash_on_merge
Optional Boolean By default false
, when merging use squash mode exampleautomations:\nsmall_change:\nif:\n- {{ files | allDocs }}\nrun:\n- action: merge@v1\nargs:\nrebase_on_merge: true\n
"},{"location":"automation-actions/#send-http-request","title":"send-http-request
","text":"The action, once triggered, sends an HTTP request to the specified URL
Args Usage Type Descriptionurl
Required String The request URL method
Optional String By default GET
, the request method headers
Optional [String] Empty by default ([]
), Key-Value list of strings, which will be sent as the HTTP headers user
Optional String Empty by default, format: 'username:password'
. If used - adds a Basic-auth HTTP header, by setting the Authorization
header. Using this arg will override any existing Authorization
header that was set using headers
body
Optional String Empty by default, the data to be sent as the request body. Only applicable for request methods PUT
, POST
, DELETE
, and PATCH
timeout
Optional String Empty by default (no timeout), the number of milliseconds before the request times out. When the time out is reached, the request will be aborted exampleautomations:\nsend_webhook:\nif:\n- true\nrun:\n- action: send-http-request@v1\nargs:\nurl: \"http://WEBHOOK_URL\"\nmethod: POST\nheaders: '{\"Content-type\": \"application/json\"}'\nbody: '{\"text\": \"Hello, world!\"}'\n
"},{"location":"automation-actions/#send-slack-message","title":"send-slack-message
","text":"The action, once triggered, sends a webhook with a message content to a Slack app. To use this action, create a Slack app with Incoming Webhooks enabled. gitStream uses the webhook URL to send the message.
Args Usage Type Descriptionmessage
Required String The message content webhook_url
Optional String The webhook URL. Use the env
variable to pass secrets exampleautomations:\nsend_slack:\nif:\n- true\nrun:\n- action: send-slack-message@v1\nargs:\nmessage: \"Hello world :tada:.\"\nwebhook_url: \"{{ slack_webhook }}\"\nslack_webhook: {{ env.SLACK_WEBHOOK }}\n
"},{"location":"automation-actions/#set-required-approvals","title":"set-required-approvals
","text":"This action, once triggered, blocks PR merge till the desired reviewers approved the PR. The actions fail the check to prevent the PR for merge.
Args Usage Type Descriptionapprovals
Required Integer Sets the number of required reviewer approvals for merge for that PR exampleautomations:\ndouble_review:\nif:\n- {{ files | match(regex=r/agent\\//) | some }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n
Attention
To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.
"},{"location":"automation-actions/#request-changes","title":"request-changes
","text":"This action, once triggered, request changes on the PR. As long as request change is set, gitStream will block the PR merge.
This is a manged action, when a PR updates existing change request by gitStream is re-evaluated and removed if no longer applicable.
Args Usage Type Descriptioncomment
Required [String] The desired request changes comment exampleautomations:\ncatch_deprecated:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/^[+].*oldFetch\\(/') | some }}\nrun:\n- action: request-changes@v1\nargs:\ncomment: |\nYou have used deprecated API `oldFetch`, use `newFetch` instead.\n
Attention
To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.
"},{"location":"automation-actions/#require-reviewers","title":"require-reviewers
","text":"This action, once triggered, requires a specific reviewer approval. The PR merge is blocked till approved by either of the listed users or teams.
Args Usage Type Descriptionreviewers
Required [String] Sets required reviewers. Supports user names and teams. Teams notated by adding a prefix with the owner name e.g. owner/team
. Merge is blocked till approved by either of the listed users also_assign
Optional Bool true
by default, also assign the specified users as reviewers exampleautomations:\nsenior_review:\nif:\n- {{ files | match(regex=r/src\\/ui\\//) | some }}\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [popeye, olive, acme/team-a]\n
Attention
To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.
"},{"location":"automation-actions/#run-github-workflow","title":"run-github-workflow
","text":"This action, once triggered, will start a workflow dispatch automation with the option to add a check to the list of checks in the PR
Args Usage Type Descriptionworkflow
Required String The ID or name of the workflow dispatch. owner
Optional String By default, the value of repo.owner
context variable. The account owner of the repository. Case insensitive. repo
Optional String By default, the value of repo.name
context variable. The name of the repository without the .git
extension. Case insensitive. ref
Optional String By default, the value of branch.name
context variable. The account owner of the repository. Case insensitive. inputs
Optional String By default, an empty list. Key-Value list with the arguments to provide to the workflow check_name
Optional String When added, after the workflow is complete, add the check name to the checks list on GitHub stop_ongoing_workflow
Optional Boolean By default, false
. In case the workflow already runs on the branch, if true
: cancel the ongoing workflow before running the newly dispatched workflow. If false
: wait for the old workflow to finish before dispatching a new one exampleon: - commit\nautomations:\nrun_workflow_dispatch:\nif:\n- {{ has.fe_code_changes }} run:\n- action: run-github-workflow@v1\nargs:\nowner: {{ repo.owner }}\nrepo: {{ repo.name}}\nworkflow: .github/workflows/frontend-manual.yml\nref: {{ branch.name }}\ncheck_name: FE-tests\nhas:\nfe_code_changes: {{ files | match(regex=r/frontend\\//) | some }}\n
Attention
All notable changes to this project will be documented in this file.
"},{"location":"changelog/#20231122","title":"2023.11.22","text":"Continuous Merge automation files have a .cm
extension. In a repository, gitStream loads and parse the .cm
directory, which can have multiple automation files, each of which is evaluated independently.
You can edit the .cm
files and add your own checks and rules. Check out the Automation examples.
There are two types of automation rules: repository level rules and organization level rules.
Repository level rules are set by creating a special .cm
directory in the repository root. Automation rules are specified in files in this directory, which can have any name but must end with .cm
.
Organization level rules are defined by creating a special repository named cm
in the organization or group. In this repository, you can add CM automation files, which will apply to all the repositories that gitStream app is connected.
When organization level rules are defines, repository level automation shall take precedence and override organization automation when having the same identifier.
An automation identifier is a composition of the CM file name and the automation name. For example when safe_changes
is defined in gitstream.cm
then the automation identifier shall be gitstream/safe_changes
Tip
You can exclude certain repositories per automation file using the config.ignore_repositories
Repository automation rules are set by creating a special .cm
directory in your repository root. Automation rules are specified in files in this directory, these files can have any name but must end with .cm
. By default, you start with a single automation file .cm/gitstream.cm
.
Every file is parsed independently, and the parsing results are combined and executed.
Specifically:
.cm
filesconfig
section is defined per .cm
file (except config.admin
)When configured correctly, your repository directory structure should look like that (for GitHub):
Repsository automation rules.\n\u251c\u2500 .cm/\n\u2502 \u2514\u2500 *.cm\n\u251c\u2500 .github/\n\u2502 \u2514\u2500 workflows/\n\u2502 \u2514\u2500 gitstream.yml\n
Note
The .cm/gitstream.cm
is special, as it allows for repository level configuration such as config.admin
.
Organization automation rules are defined by creating a special repository cm
in your organization or group. In this repository, you can add CM automation files, which will apply to all the repositories that gitStream app is connected.
When configured correctly, the cm
repository directory structure should look like that (for GitHub):
.\n\u251c\u2500 *.cm\n\u251c\u2500 .github/\n\u2502 \u2514\u2500 workflows/\n\u2502 \u2514\u2500 gitstream.yml\n
For each PR the following automation rules are applied:
When organization level rules are defined, then the CI/CD will be executed on the cm
repository on behalf of the PR repository.
By utilizing the following techniques, you can effectively combine and manage global and repository rules to customize the behavior of your automations to fit the specific requirements of your repositories:
cm
repository and are applied to all repositories that are connected to gitStream.cm
repository and add a list of the unwanted repositories under the config.ignore_repositories
property in the CM file.The following sections are used in .cm
file to describe the desired automations:
manifest
config
automations
manifest
","text":"The first section in a gitstream.cm
file is the manifest
.
manifest:\nversion: 1.0\n
The only field required is version
.
manifest
Y Map The manifest section root manifest.version
Y String Specify the .cm
spec version: 0.1, 1.0 The manifest version field is used to parse the .cm
file, in the future if breaking changes are introduced to the parser then older automation will be still supported.
config
","text":"The config
section is optional in the .cm
file and is used to specify configuration for the way gitStream works.
config
Map - per .cm
file The config section, applies for the automations defined in the current file config.admin.users
[String] []
gitstream.cm
Admin user list (use the Git provider user names) config.ignore_files
[String] []
per .cm
file Exclude specific files config.ignore_repositories
[String] []
per .cm
file Exclude specific repositories config.user_mapping
[String: String] []
per .cm
file Key value list of Git user detailes and Git provider account names"},{"location":"cm-file/#configadminusers","title":"config.admin.users
","text":"When specified in gitstream.cm
the config.admin.users
allows adding admin rights, when a PR changes the *.cm
files only, if the user is listed in config.admin.users
the PR will be then approved by gitStream. For example, setting popeye
as admin:
config:\nadmin:\nusers: ['popeye']\n
This configuration is valid only when used in .cm/gitstream.cm
, when defined in other .cm
files this configuration is ignored.
When you add a user to config.admin.users
in your organization's cm
repository, they are granted administrative privileges to CM changes across every repository in the organization. gitStream evaluates CM rules in the individual repository and your organization's cm
repository to determine admin users.
config.ignore_files
","text":"The config.ignore_files
supports glob pattern matching that contains a list of files to ignore.
Common usage, since some files such as lock files are intentionally not a required part of a review, they would not want to them to be counted in the estimated review time. In such cases, you can add config.ignore_files
to the relevant CM file, for example:
config:\nignore_files:\n- 'yarn.lock'\n- 'package-lock.json'\n- 'openapi.json'\n- 'ui/src/**/*Model.d.ts'\n
"},{"location":"cm-file/#configignore_repositories","title":"config.ignore_repositories
","text":"The config.ignore_repositories
contains a list of repositories to ignore, for example:
config:\nignore_repositories:\n- services\n- common\n
For the listed repositories, the automation defined in the CM file shall not apply.
"},{"location":"cm-file/#configuser_mapping","title":"config.user_mapping
","text":"Accepts list of key value strings.
For example, when using rankByGitBlame
or explainRankByGitBlame
Git users are mapped to their matching Git provider accounts based on the Git details. The automatic mapping can sometimes result with the wrong account or fail to find a proper mapping, in these cases you can configure the config.user_mapping
. This allows you to map confusing Git user into their specific accounts and dump some irrelevant accounts:
config:\nuser_mapping:\n- 'Popeye Man <popeye@invalid.com>': 'popeye-the-salyor-man' # (1)\n- 'Popeye Man <popeye2@invalid.com>': 'popeye-the-salyor-man' # (2)\n- 'olive <olive@invalid.com>': null # (3)\n
null
removes this Git user from the suggested resultsWhen using rankByGitBlame
to assign reviewers automatically with add-reviewers@v1
then mapping users to null
is a way to prevent the automatic mapping in certain cases, like in your example contributors that are not longer part of the team.
On the other hand, when using explainRankByGitBlame
with add-comment@v1
it still shows these users details in the PR comment suggestion as this info might be valuable by itself.
- action: add-reviewers@v1\nargs: # (1)\nreviewers: {{ repo | rankByGitBlame(gt=25) }}\n- action: add-comment@v1\nargs: # (2)\ncomment: |\n{{ repo | explainRankByGitBlame(gt=25) }}\n
rankByGitBlame
will drop null
usersexplainRankByGitBlame
will NOT drop null
usersautomations
","text":"The automations
section defines the automations and their conditions.
automations:\nmark_small_pr:\nif:\n- {{ checks.size.is.xsmall }}\nrun:\n- action: add-label@v1\nargs:\nlabel: xsmall\n
Each automation includes its name, and few fields: if
and run
.
automations
Y Map The automations section root automations.NAME
Y Map User defined name of the automation, can be any string automations.NAME.if
Y Map List of conditions with AND relationship automations.NAME.run
Y Map Actions to run if all conditions are met, invoked one by one The if
field includes the list of conditions. The conditions are checked when a pull request is opened or changed, if all the conditions pass, the automation is executed.
The run
field includes the automation to execute. It includes the following fields:
action
Y String The action pointer engine
N String The action engine, default is gitstream
args
N List The action inputs list For gitstream
engine, the action is specified by: name@version
gitStream supported actions, see actions.
"},{"location":"cm-file/#reusing-checks","title":"Reusing checks","text":"You can define an accessory section, e.g. checks
, that defines common conditions, and reuse.
size:\nis:\nsmall: {{ branch.diff.size < 20 }}\nmedium: {{ branch.diff.size >= 20 and branch.diff.size < 100 }}\nlarge: {{ branch.diff.size >= 100 }}\nautomations:\napprove_small:\nif:\n- {{ size.is.small }}\nrun:\n- action: approve@v1\nmark_small_medium:\nif:\n# Check that the PR is either small or medium size\n- {{ size.is.small or size.is.medium }}\n# AND its less than 5 minutes review (estimated)\n- {{ branch | estimatedReviewTime <= 5 }}\nrun:\n- action: add-label@v1\nargs:\nlabel: 'good-size'\n
"},{"location":"cm-syntax/","title":"Cm syntax","text":"Deprecated. See: /how-it-works
"},{"location":"context-variables/","title":"Context variables","text":"Context variable are the inputs for the automation conditions or checks.
Legend
The icons indicate the availability status of each action.
gitStream includes a collection of variables called contexts.
branch
env
files
pr
repo
source
The following structures are used in the context objects:
GitBlame
Check
Contributor
FileDiff
FileMetadata
Comment
conversations
Partial example of a context object for a PR that changed few lines in a README.md
file:
{\n\"branch\": {\n\"name\": \"new-feature-branch\",\n\"base\": \"main\",\n\"diff\": {\n\"size\": 50,\n\"files_metadata\": [\n{\n\"original_file\": \"README.md\",\n\"new_file\": \"README.md\",\n\"deletions\": 0,\n\"additions\": 2\n}\n]\n},\n\"num_of_commits\": 1\n},\n\"source\": {\n\"diff\": {\n\"files\": [\n{\n\"original_file\": \"README.md\",\n\"new_file\": \"README.md\",\n\"diff\": \"@@ -10,3 +10,5 @@ This project \\n+\\n+## Intro\",\n\"original_content\": \"This project \\n\",\n\"new_content\": \"This project \\n\\n## Intro\"\n}\n]\n}\n},\n\"repo\": {\n\"contributors\": {\n\"popeye\": \"46\",\n\"olive\": \"6\"\n},\n\"owner\": \"acme\"\n},\n\"files\": [\n\"README.md\"\n]\n}\n
"},{"location":"context-variables/#reference","title":"Reference","text":""},{"location":"context-variables/#branch","title":"branch
","text":"The branch
context contains info regarding the branch changes compared to the base branch.
Note
compared to the source
context does not include actual source code.
branch
Map Includes the info related to the current branch branch.author
String The branch author (the user that did first commit in the branch). The formatted like author in git-log
, e.g. Popeye <popeye@acme.com>
branch.author_name
String The branch author name branch.author_email
String The branch author email branch.base
String The main branch, main
branch.commits.messages
[String] A list with all the commit messages in this branch branch.diff.size
Integer The sum of line changed: additions, edits and deletions branch.diff.files_metadata
FileMetadata
List of changed files including their relative path branch.name
String The current branch, feature-123-branch
branch.num_of_commits
Integer The number of commits in the branch The branch context doesn't include any source code, but only related metadata.
Example for using branch.name
and branch.author
to automatically approve and merge version bumps.
automations:\ndependabot:\nif:\n- {{ branch.name | includes(term=\"dependabot\") }}\n- {{ branch.author | includes(term=\"dependabot\") }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: \"approved-dependabot\"\n- action: merge@v1\nargs:\nwait_for_all_checks: true\nsquash_on_merge: true\n
Tip
The files
context doesn't include deleted file, to identify both modified and deleted files use the branch.diff.files_metadata
, for example:
{{ branch.diff.files_metadata | match(attr='file', regex=r/\\.md$/) | every }}\n
"},{"location":"context-variables/#env","title":"env
","text":"The env
context allows the user to pass data from the repo that is unavailable in the other context variables. Thus, the structure of the variable is not fixed and depends on user configuration.
To configure the env
variable, add the env
field to gitstream's workflow job configurations on .github/workflows/gitstream.yml
, under the Evaluate Rules
step. For more information, visit GitHub's guide for Using secrets in GitHub Actions The env
field examle: add secrets to the env variable
...\nname: gitStream workflow automation\nsteps:\n- name: Evaluate Rules\nenv:\nSLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}\n...\n
To use the context variable, access to the env
variable's fields as configured in gitstream.yml
automations:\nsend_slack:\nif:\n- true\nrun:\n- action: send-slack-message@v1\nargs:\nmessage: \"Hello world :tada:.\"\nwebhook_url: \"{{ slack_webhook }}\"\nslack_webhook: {{ env.SLACK_WEBHOOK }}\n
"},{"location":"context-variables/#files","title":"files
","text":"The files
context includes the list of changed files in the branch compared to the main branch.
files
[String] List of all changed files with their full path For example, a typical files
context can look like this:
[\n\"README.md\",\n\"package.json\",\n\"src/app.js\",\n\"src/index.js\",\n\"docs/examples.md\"\n]\n
Example for checking if certain changes are made:
automations:\nui_review:\nif:\n- {{ files | match(list=ui_templates_files) | some }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [GitHubUser1, GitHubUser2]\nui_templates_files:\n- resources/app/ui_template.yml\n- resources/app/role_template.yml\n- resources/app/account_template.yml\n
"},{"location":"context-variables/#pr","title":"pr
","text":"The pr
context includes metadata related to the pull request.
pr
Map Includes the info related to the PR pr.approvals
[String] A list of the of reviewers that approved the PR pr.author
String The PR author name pr.author_teams
String The teams which the PR author is member of pr.author_is_org_member
Bool true
if the PR author is a member of the organization where gitStream is installed pr.checks
[Check
] List of checks, names and status pr.comments
[Comment
] List of PR comments objects pr.conflicted_files_count
Integer The number files in the PR with conflicts pr.conversations
[Conversation
] List of PR conversation objects, usually when reviewer have comments about the source code pr.created_at
String The date and time the PR was created pr.draft
Bool true
when the PR is marked as Draft/WIP pr.description
String The PR description text pr.labels
[String] The labels that are attached to the PR pr.number
Integer The PR or MR Id number pr.provider
String The Git cloud provider name, e.g. GitHub
, GitLab
etc. pr.reviewers
[String] The list of reviewers set for this PR pr.status
String The PR status: open
, closed
and merged
pr.target
String The branch the PR is intended merged into pr.title
String The PR title pr.requested_changes
[String] List of users that requested changes pr.reviews
[Review
] List of PR reviews, relevant in GitHub pr.unresolved_threads
Integer The number of open review comments in the PR pr.updated_at
String The date and time the PR was last updated Example for checking the PR title includes a Jira ticket:
automations:\ncheck_jira_ticket:\nif:\n- {{ not has.jira_ticket }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-ticket\"\ncolor: 'F6443B'\nhas:\njira_ticket: {{ pr.title | includes(regex=r/^\\[?\\w{3,4}-\\d{1,6}\\]?(\\s|-|_).{20,}$/) }}\n
"},{"location":"context-variables/#repo","title":"repo
","text":"The repo
context includes metadata related to the repo.
repo
Map Includes the info related to the current repo repo.age
Integer Number of days since first commit (of any user) repo.author_age
Integer number of days since first commit to this repo repo.blame
GitBlame
The percentage each user's lines in a file, the list includes all changed files in the branch. The list is sorted by the ratio
field repo.contributors
Contributor
List of contributors in the repo repo.git_activity
GitActivity
Per file and user, the number of lines changed every week for the last 52 weeks repo.name
String Repository name repo.owner
String Repository owner account name repo.visibility
String The visibility of the source branch repo. Value is one of: private
, internal
, or public
"},{"location":"context-variables/#source","title":"source
","text":"The source
context includes a list of FileDiff
objects that can be used to get insights based on code changes. The changes compared to the latest main branch.
source.diff.files
FileDiff
List of changed files with their code changes The source context include all code changes, it is not safe to share it with unknown services.
"},{"location":"context-variables/#check-structure","title":"Check
structure","text":"{\n\"name\": String, # The check name\n\"status\": String, # The check status: `queued`, `in_progress`, `completed`\n\"conclusion\": String, # The check conclusion: `action_required`, `cancelled`, `failure` `neutral`, `success`, `skipped`, `stale`, `timed_out`\n}
"},{"location":"context-variables/#comment-structure","title":"Comment
structure","text":"{\n\"commenter\": String, # The user that add the comment\n\"content\": String, # The comment body \"created_at\": String, # The time on which the comment was created\n\"updated_at\": String, # The time on which the comment was last updated\n}
"},{"location":"context-variables/#conversation-structure","title":"Conversation
structure","text":"{\n\"commenter\": String, # The user that add the comment \"content\": String, # The comment body \"created_at\": String, # The time on which the comment was created \"updated_at\": String, # The time on which the comment was updated \"start_line\": Integer, # The first line marked for this comment \"end_line\": Integer, # The last line marked for this comment \"is_resolved\": Boolean # `true` when marked as resolved\n}\n
"},{"location":"context-variables/#contributor-structure","title":"Contributor
structure","text":"The repo.contributors
mapping includes a list of Contributor
, where the user name is used as dynamic key:
{\nUSER_NAME: Integer # Number of commits\n}
"},{"location":"context-variables/#filediff-structure","title":"FileDiff
structure","text":"The source.diff.files
mapping includes a list of FileDiff
:
{\n\"diff\": String, # The content in diff format `+` for additions, `-` for deletions\n\"new_content\": String, # The new content in this branch\n\"new_file\": String, # The name of the file after the changes, including its path\n\"original_content\": String, # The content as is in the `main` branch\n\"original_file\": String, # The name of the file before the changes, including its path\n}
"},{"location":"context-variables/#filemetadata-structure","title":"FileMetadata
structure","text":"The branch.diff.files_metadata
mapping includes a list of FileMetadata
:
{\n\"additions\": Integer, # The number of lines edited or added to the file\n\"deletions\": Integer, # The number of lines removed from the file \"file\": String, # The name of the file before the changes, including its path\n}
For example, sum additions in javascript code files:
{{ branch.diff.files_metadata | filter(attr='new_file', regex=r/\\.js$|\\.ts$/) | map(attr='additions') | sum }}\n
"},{"location":"context-variables/#gitactivity-structure","title":"GitActivity
structure","text":"This structure include per changed file, for every user, the number of lines changed every week for the last 52 weeks.
{\nFILE_NAME: # The file name and path\n{ # The git user identifier (String)\nGIT_USER: {\n\"week_INDEX\": Integer # Number of lines changed that week\n# ... for the last 52 weeks }\n}\n}\n
For example:
{\n\"src/utils/service.js\": {\n\"popeye <popeye@acme.com>\": {\n\"week_1\": 20, \"week_2\": 15, \"week_10\": 250\n},\n\"olive <olive@acme.com>\": {\n\"week_1\": 3, \"week_3\": 50, \"week_52\": 250\n}\n},\n\"README.md\": {\n\"popeye <popeye@acme.com>\": {\n\"week_2\": 15, \"week_3\": 10\n}\n}\n}\n
"},{"location":"context-variables/#gitblame-structure","title":"GitBlame
structure","text":"For each file, a list of user's blame ratio.
{\nFILE_NAME: # The file name and path\n{ # The git user identifier (String)\nGIT_USER: Integer, # Precentage 0-100, ratio of user's lines / total lines in file\n}\n}\n
For example:
{\n\"src/utils/service.js\": {\n\"popeye <popeye@acme.com>\": 78,\n\"olive <olive@acme.com>\": 22,\n},\n\"README.md\": {\n\"popeye <popeye@acme.com>\": 13,\n\"olive <olive@acme.com>\": 22,\n\"brutus <brutus@acme.com>\": 65,\n}\n}\n
"},{"location":"context-variables/#review-structure","title":"Review
structure","text":"{\n\"commenter\": String, # The user that add the comment\n\"content\": String, # The comment body \"created_at\": String, # The time on which the comment was created\n\"state\": String, # Either `approved`, `changes_requested`, `commented`, `pending`, `submitted`\n\"conversations\": [Conversation], # Conversations that are relvant to this Review feedback\n}
"},{"location":"dry-run-mode/","title":"How to Test Your Automation","text":"By default, gitStream runs all applicable automations for every new PR and change to existing PR. If you want to test and experiment with new rules, gitStream supports a dry-run mode that will avoid making changes to your PRs. When you commit changes to any CM files found inside your repo's .cm/
directory, gitStream will switch to dry-run mode.
In dry-run mode, gitStream won't execute any automation rules on the PR. Instead, gitStream will parse all applicable automation rules and post a comment to the PR discussion that describes the actions that will be taken for normal PRs. A new comment will be added after every new commit.
Note
When in dry-run mode, incoming changes to the CM files are ignored. In other words, new automations and configurations won't take effect until you merge the PR.
Once you are satisfied with the results, you can merge your CM changes into the main branch to enable the new configurations.
"},{"location":"examples/","title":"gitStream Quickstart","text":"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.
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:
Label Management with gitStream
# -*- mode: yaml -*-\n# +----------------------------------------------------------------------------+\n# | /:\\ gitStream: Workflow automation for the code review process. |\n# +----------------------------------------------------------------------------+\n# | This file contains one or more /:\\ gitStream automations: |\n# | https:// docs.gitstream.cm |\n# | |\n# | gitStream uses YAML syntax with nunjucks templating via Jinja 2. |\n# | |\n# | Automations follow an \"if this, then that\" execution format. |\n# | More info here: https://docs.gitstream.cm/how-it-works/ |\n# | |\n# +----------------------------------------------------------------------------+\n# /:\\ gitStream Reference Docs: \n# Context Variables: https://docs.gitstream.cm/context-variables/\n# Filter Functions: https://docs.gitstream.cm/filter-functions/\n# Automation Actions: https://docs.gitstream.cm/automation-actions/\nmanifest:\nversion: 1.0\n# +----------------------------------------------------------------------------+\n# | Automations\n# +----------------------------------------------------------------------------+\nautomations:\n# Apply color coded labels to PRs based on the estimated time to review.\n# https://docs.gitstream.cm/automations/provide-estimated-time-to-review/\nestimated_time_to_review:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"{{ calc.etr }} min review\"\ncolor: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}\n# Flag PRs that are missing a Jira ticket reference in the title or description.\n# https://docs.gitstream.cm/integrations/jira/\nlabel_missing_jira_info:\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: {{ colors.red }}\n# Flag PRs that have unresolved comment threads.\n# https://docs.gitstream.cm/automations/standard/label-management/label-unresolved-threads/\nlabel_unresolved_threads: if:\n- {{ pr.status == 'open' }} - {{ pr.unresolved_threads }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \ud83d\udea8 {{ pr.unresolved_threads }} Unresolved Thread(s)\ncolor: {{ colors.yellow }} # Flag PRs that delete files to highlight potential refactors that need extra scrutiny.\n# https://docs.gitstream.cm/automations/label-deleted-files/\nflag_deleted_files:\nif:\n- {{ has.deleted_files }}\nrun: - action: add-label@v1\nargs:\nlabel: \ud83d\uddd1\ufe0f Deleted files\ncolor: {{ colors.orange }}\n# +----------------------------------------------------------------------------+\n# | Custom Expressions |\n# | https://docs.gitstream.cm/how-it-works/#custom-expressions |\n# +----------------------------------------------------------------------------+\n# https://docs.gitstream.cm/filter-functions/#estimatedreviewtime\ncalc:\netr: {{ branch | estimatedReviewTime }}\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\ndeleted_files: {{ source.diff.files | map(attr='new_file') | match(term='/dev/null') | some }}\n# These are all of the colors in GitHub's default label color palette.\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\ngreen: '0e8a16'\nblue: '1d76db'\npurple: '5319e7'\n
Download this example as a CM file. "},{"location":"examples/#automatically-route-pr-reviews","title":"Automatically Route PR Reviews","text":"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:
Review Routing with gitStream
# -*- mode: yaml -*-\n# +----------------------------------------------------------------------------+\n# | WARNING: This file controls repo automations, use caution when modifying |\n# +----------------------------------------------------------------------------+\n# | This file contains one or more /:\\ gitStream automations: |\n# | https:// docs.gitstream.cm |\n# | |\n# | gitStream uses YAML syntax with nunjucks templating via Jinja 2. |\n# | |\n# | Automations follow an \"if this, then that\" execution format. |\n# | More info here: https://docs.gitstream.cm/how-it-works/ |\n# | |\n# +----------------------------------------------------------------------------+\n# /:\\ gitStream Reference Docs: \n# Context Variables: https://docs.gitstream.cm/context-variables/\n# Filter Functions: https://docs.gitstream.cm/filter-functions/\n# Automation Actions: https://docs.gitstream.cm/automation-actions/\nmanifest:\nversion: 1.0\n# +----------------------------------------------------------------------------+\n# | Customize This Section |\n# +----------------------------------------------------------------------------+\n# Change review_team to match your organization or repo's primary review team. \n# The format is Git Organization Name / Team Name\nreview_team: 'my-org/team-name'\n# List of files that should trigger a sensitive file change review.\nsensitive:\n- App.tsx\n- AppRoot.tsx\n# Files to exclude from gitStream automations.\nconfig:\nignore_files:\n- 'yarn.lock'\n- 'ios/*.lock'\n- 'android/*.lock'\n# Set long_review_threshold to the number of minutes that should trigger extra review requirements.\nlong_review_threshold: 5\n# +----------------------------------------------------------------------------+\n# | Automations\n# +----------------------------------------------------------------------------+\nautomations:\n# Post a comment that recommends reviewers based on their knowledge of the files in the PR.\n# https://docs.gitstream.cm/automations/standard/explain-code-experts/\nexplain_code_experts:\n# Alternatively, if you only want to trigger when the slash command `/gitstream suggest-reviewers` is included in a comment,\n# change '- true' to '- {{ (pr.comments | match(attr='content', term='/gitstream suggest-reviewers') | some) }}'\nif:\n- true\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10\n# Automatically approve changes that only affect formatting, documentation, tests, or images\n# https://docs.gitstream.cm/automations/approve-safe-changes/\napprove_safe_changes:\nif:\n- {{ is.safe_change }}\n# Apply a safe change label, approve the PR and explain why in a comment.\nrun: - action: add-label@v1\nargs:\nlabel: 'Safe Change'\ncolor: {{ colors.green }}\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is considered a safe change and has been automatically approved.\n# Set criteria for PRs that only need one reviewer.\n# This helps reduce the review burden for low-risk PRs.\nrequire_one_review:\nif:\n- {{ not has.sensitive_files }}\n- {{ is.quick_review }}\n- {{ approvals.zero }}\nrun:\n- action: add-label@v1\nargs: label: \u23f3 Waiting for 1 reviewer\ncolor: {{ colors.yellow }}\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ review_team }}]\nunless_reviewers_set: true\n- action: set-required-approvals@v1\nargs:\napprovals: 1\n# Set criteria for PRs that need extra reviewers.\n# This helps bring in extra scrutiny for large PRs or PRs that touch sensitive parts of the code.\nrequire_two_reviews:\nif:\n- {{ is.long_review or has.sensitive_files }}\n- {{ approvals.ltTwo }}\nrun:\n- action: add-label@v1\nargs: label: {{ '\u23f3 Waiting for 2 reviewers' if (approvals.zero) else '\u23f3 Waiting for 1 reviewer' }}\ncolor: {{ colors.yellow }}\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ review_team }}]\nunless_reviewers_set: true\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n# Flag low-risk PRs that are ready to merge.\nflag_quick_review_merge:\nif:\n- {{ not has.sensitive_files }}\n- {{ is.quick_review }}\n- {{ not has.do_not_merge_label }}\n- {{ approvals.gtZero }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \u270c\ufe0f Ready to merge\ncolor: {{ colors.green }}\n# Flag higher risk PRs that are ready to merge.\nflag_large_review_merge:\nif:\n- {{ is.long_review or has.sensitive_files }}\n- {{ approvals.gtOne }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \u270c\ufe0f Ready to merge\ncolor: {{ colors.green }}\n# +----------------------------------------------------------------------------+\n# | Custom Expressions |\n# | https://docs.gitstream.cm/how-it-works/#custom-expressions |\n# +----------------------------------------------------------------------------+\n# https://docs.gitstream.cm/filter-functions/#estimatedreviewtime\ncalc:\netr: {{ branch | estimatedReviewTime }}\nhas:\nsensitive_files: {{ files | match(list=sensitive) | some }}\ndo_not_merge_label: {{ pr.labels | match(term='Do not merge') | some }}\nis:\nsafe_change: {{ (source.diff.files | isFormattingChange) or (files | allDocs) or (files | allTests) or (files | allImages) }}\nquick_review: {{ files | length <= 7 and calc.etr <= long_review_threshold }}\nlong_review: {{ files | length > 7 or calc.etr > long_review_threshold }}\napprovals:\nzero: {{ pr.approvals | length == 0 }}\ngtZero: {{ pr.approvals | length > 0 }}\ngtOne: {{ pr.approvals | length > 1 }}\nltTwo: {{ pr.approvals | length < 2 }}\n# These are all of the colors in GitHub's default label color palette.\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\ngreen: '0e8a16'\nblue: '1d76db'\npurple: '5319e7'\n
Download this example as a CM file. "},{"location":"examples/#next-step","title":"Next Step","text":"For a more detailed list of automations, check out the gitStream integrations page or automation library.
"},{"location":"execution-model/","title":"Execution Model","text":"gitStream is triggered on new pull requests (PRs) for repositories that have gitStream installed. Upon triggering, gitStream collects context variables and evaluates the automation rules to determine which automation rules are relevant.
"},{"location":"execution-model/#organization-level-rules-and-repository-rules","title":"Organization level rules and repository rules","text":"When a central cm
repository is set with the CI/CD runner, the events for PRs from all installed repositories shall be evaluated in the cm
repository pipeline, taking into account the organization level rules and the PR repository rules.
By default, gitStream evaluates any new commit that is pushed to the PR, triggering automation evaluation.
Additionally, if any of the automation rules reference the pr
context, gitStream shall trigger and will initiate automation rules evaluation even where there are changes to the PR title, descriptions, labels or comments.
This allows for greater flexibility in the automation process, ensuring that the relevant automation rules are evaluated and triggered when necessary. The execution model ensures that the automation process is streamlined, efficient, and effective.
"},{"location":"execution-model/#explicit-triggers","title":"Explicit triggers","text":"gitstream supports an explicit triggering mechanism. When using explicit triggers, the automations will run only according to the defined triggers, which means the Implicit triggers will not work. Automations triggered by explicit triggers will also be invoked on draft
PRs
Use explicit triggers to enhance the control and customization of automations in gitStream, allowing users to define precisely when and how automations should be triggered based on various events and actions within pull requests.
Add the on
keyword to the file and/or to a specific automation to define explicit triggers. gitStream supports the following explicit triggers:
merge
Trigger when merging the PR pr_created
Trigger when the PR is created commit
Trigger on each commit after the creation of the PR comment_added
Trigger on each added comment label_added
Trigger on each added label label_removed
Trigger on removed label Explicit triggers are set per each automation block independently and can be configured at the file level, specific to each automation separately or a combination of the two. In case triggers are listed at the file level and specific automation, the automation will be triggered according to both triggers. If an automation block does not have explicit triggers configured, it will be triggered according to the default (implicit) triggers
Examples
assign code expert reviewer when the PR is created and after each commit
on:\n- pr_created\n- commit\nautomations:\nassign_code_experts:\nif:\n- true\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=10) }}\n
Explain code experts only if the label \u201csuggest-reviewer\u201d exists. The automation will be triggered after each commit and after each label addition. If the label \u201csuggest-reviewer\u201d exists, it will trigger the explain-code-experts
automation
on:\n- commit\nautomations:\nexplain_code_experts:\non:\n- label_added\nif:\n- {{ pr.labels | match(term='suggest-reviewer') | some }}\nrun:\n- action: explain-code-experts@v1\nargs:\ngt: 10\n
In your repo permissions, make sure GitHub actions are permitted:
Go to Repo's settings > Actions > General > Actions permissions
Choose which repositories are permitted to use GitHub Actions.
[x] Allow all actions and reusable workflows
"},{"location":"faq/#does-gitstream-services-have-access-to-my-code","title":"Does gitStream services have access to my code?","text":"Like any other CI/CD automation, the source code is being scanned in the repo and is not shared with any external services. Only metadata that relates and affects the workflow is shared to allow rule based automation on the repo.
"},{"location":"faq/#why-does-gitstream-require-permission-to-write-code","title":"Why does gitStream require permission to write code?","text":"In order to support automations that either Approve or Merge PRs, GitHub API requires code write scope.
"},{"location":"faq/#what-repos-are-supported","title":"What repos are supported?","text":"Any repo in GitHub is supported. More Git providers are planned soon.
"},{"location":"faq/#can-i-use-gitstream-with-merge-queues","title":"Can I use gitStream with Merge Queues?","text":"Yes. When a merge queue is used, and gitStream is set as a required check, gitStream automation will be invoked with the merge event. The automation will set gitStream to a Completed
status and Skipped
conclusion to allow the PR merge.
Coming soon.
"},{"location":"faq/#is-there-cm-syntax-highlighting","title":"Is there .cm syntax highlighting?","text":"The .cm
file use YAML with JINJA2, in order for your favorite editor to choose automatically the right syntax, you can use modelines.
Add the following line to the top of the .cm
file (the default has it already):
# -*- mode: yaml -*-\n
Get a plug-in that enable modelines, popular ones are:
Go to our issues page and check if there are any similar issues already reported. If not, create a new issue with all the details so we can take a look.
Found a bug? Create a new item in the project's issues
"},{"location":"filter-function-plugins/","title":"Filter Function Plugin Library","text":"JavaScript plugins that enable custom filter functions for gitStream. To learn how to use these examples, read our guide on how to use gitStream plugins.
"},{"location":"filter-function-plugins/#comparesemver","title":"compareSemver","text":"Compares two software version numbers (e.g., \"1.2.1\" or \"1.2b\") and determines the type of version change. The first version to be compared, and the second are passed as argument 1 and 2 or as array of 2 items. When V1 > V2 the it means and upgrade.
Returns: string
- It returns a string of either: 'major' if the major version is incremented. 'minor' if the minor version is incremented. 'patch' if the patch version is incremented. 'downgrade' if the second version is lower than the first. 'equal' if both versions are equal. 'error' if the comparison is abnormal or cannot be determined. License: MIT
Array.<string>
V1 and V2 in Semver format [lexicographical] boolean
false
compares each part of the version strings lexicographically instead of naturally; this allows suffixes such as \"b\" or \"dev\" but will cause \"1.10\" to be considered smaller than \"1.2\". [zeroExtend] boolean
true
changes the result if one version string has less parts than the other. In this case the shorter string will be padded with \"zero\" parts instead of being considered smaller. Example
{{ [\"1.2.1\", \"1.2.3\"] | compareSemver == \"patch\" }}\n
Plugin Code: compareSemver /**\n * @module compareSemver\n * @description Compares two software version numbers (e.g., \"1.2.1\" or \"1.2b\") and determines the type of version change.\n * The first version to be compared, and the second are passed as argument 1 and 2 or as array of 2 items. \n * When V1 > V2 the it means and upgrade.\n * @param {string[]} versions - V1 and V2 in Semver format\n * @param {boolean} [lexicographical=false] - compares each part of the version strings lexicographically instead of naturally; \n * this allows suffixes such as \"b\" or \"dev\" but will cause \"1.10\" to be considered smaller than \"1.2\".\n * @param {boolean} [zeroExtend=true] - changes the result if one version string has less parts than the other. In\n * this case the shorter string will be padded with \"zero\" parts instead of being considered smaller.\n * @returns {string} It returns a string of either:\n * 'major' if the major version is incremented.\n * 'minor' if the minor version is incremented.\n * 'patch' if the patch version is incremented.\n * 'downgrade' if the second version is lower than the first.\n * 'equal' if both versions are equal.\n * 'error' if the comparison is abnormal or cannot be determined.\n * @example {{ [\"1.2.1\", \"1.2.3\"] | compareSemver == \"patch\" }}\n * @license MIT\n**/\nmodule.exports = (v1, v2, options = {}) => {\nconsole.log(\"SEMVER\", {v1, v2, options});\n// support array as input \nif (Array.isArray(v1) && v2 === undefined) {\n[v1, v2] = v1; // Destructure the first two elements of the array into v1 and v2\n}\nconst { lexicographical = false, zeroExtend = true } = options;\nlet v1parts = (v1 || \"0\").split('.');\nlet v2parts = (v2 || \"0\").split('.');\nconst isValidPart = x => lexicographical ? /^\\d+[A-Za-z\u03b1\u00df]*$/.test(x) : /^\\d+[A-Za-z\u03b1\u00df]?$/.test(x);\nif (!v1parts.every(isValidPart) || !v2parts.every(isValidPart)) {\nreturn 'error';\n}\nif (zeroExtend) {\nconst maxLength = Math.max(v1parts.length, v2parts.length);\nv1parts = [...v1parts, ...Array(maxLength - v1parts.length).fill(\"0\")];\nv2parts = [...v2parts, ...Array(maxLength - v2parts.length).fill(\"0\")];\n}\nconst convertPart = x => {\nconst match = /[A-Za-z\u03b1\u00df]/.exec(x);\nreturn Number(match ? x.replace(match[0], \".\" + x.charCodeAt(match.index)) : x);\n};\nif (!lexicographical) {\nv1parts = v1parts.map(convertPart);\nv2parts = v2parts.map(convertPart);\n}\nfor (let i = 0; i < v1parts.length; i++) {\nif (v1parts[i] !== v2parts[i]) {\nif (v1parts[i] < v2parts[i]) {\nreturn 'downgrade';\n}\nswitch (i) {\ncase 0: return 'major';\ncase 1: return 'minor';\ncase 2: return 'patch';\ndefault: return 'error';\n}\n}\n}\nreturn 'equal';\n}\n
gitStream CM Example: compareSemver manifest:\nversion: 1.0\nautomations:\nbump_minor:\nif:\n- {{ bump == 'minor' }}\nrun:\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nbot `minor` version bumps are approved automatically.\nbump_patch:\nif:\n- {{ bump == 'patch' }}\nrun:\n- action: approve@v1\n- action: merge@v1\n- action: add-comment@v1\nargs:\ncomment: |\nbot `patch` version bumps are approved and merged automatically.\nbump: {{ [\"1.2.1\", \"1.2.3\"] | compareSemver }}\n
Download Source Code
"},{"location":"filter-function-plugins/#extractdependabotversionbump","title":"extractDependabotVersionBump","text":"Extract version bump information from Dependabot PRs description
Returns: Array.<string>
- V1 (to) and V2 (from) License: MIT
string
the PR description Example
{{ pr.description | extractDependabotVersionBump | compareSemver }}\n
Plugin Code: extractDependabotVersionBump /**\n * @module extractDependabotVersionBump\n * @description Extract version bump information from Dependabot PRs description\n * @param {string} description - the PR description\n * @returns {string[]} V1 (to) and V2 (from)\n * @example {{ pr.description | extractDependabotVersionBump | compareSemver }}\n * @license MIT\n**/\nmodule.exports = (desc) => {\nif (desc && desc !== '\"\"' && desc !== \"''\" ) { const matches = /Bumps.*from ([\\d\\.]+[A-Za-z\u03b1\u00df]*) to ([\\d\\.]+[A-Za-z\u03b1\u00df]*)/.exec(desc);\nif (matches && matches.length == 3) {\nvar [_, from, to] = matches;\n// remove trailing dot on to\nif (to[to.length - 1] === \".\") {\nto = to.slice(0, -1);\n}\nreturn [to, from];\n}\n}\nreturn null;\n}\n
gitStream CM Example: extractDependabotVersionBump manifest:\nversion: 1.0\nautomations:\nbump_minor:\nif:\n- {{ bump == 'minor' }}\n- {{ branch.name | includes(term=\"dependabot\") }}\n- {{ branch.author | includes(term=\"dependabot\") }}\nrun:\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nDependabot `minor` version bumps are approved automatically.\nbump_patch:\nif:\n- {{ bump == 'patch' }}\n- {{ branch.name | includes(term=\"dependabot\") }}\n- {{ branch.author | includes(term=\"dependabot\") }}\nrun:\n- action: approve@v1\n- action: merge@v1\n- action: add-comment@v1\nargs:\ncomment: |\nDependabot `patch` version bumps are approved and merged automatically.\nbump: {{ pr.description | extractDependabotVersionBump | compareSemver }}\n
Download Source Code
"},{"location":"filter-function-plugins/#extractsnykversionbump","title":"extractSnykVersionBump","text":"Extract version bump information from Snyk PRs description
Returns: Array.<string>
- V1 (to) and V2 (from) License: MIT
string
the PR description Example
{{ pr.description | extractSnykVersionBump | compareSemver }}\n
Plugin Code: extractSnykVersionBump /**\n * @module extractSnykVersionBump\n * @description Extract version bump information from Snyk PRs description\n * @param {string} description - the PR description\n * @returns {string[]} V1 (to) and V2 (from)\n * @example {{ pr.description | extractSnykVersionBump | compareSemver }}\n * @license MIT\n**/\nmodule.exports = (desc) => {\nif (desc && desc !== '\"\"' && desc !== \"''\" ) { const matches = /Upgrade.*from ([\\d\\.]+[A-Za-z\u03b1\u00df]*) to ([\\d\\.]+[A-Za-z\u03b1\u00df]*)/.exec(desc);\nif (matches && matches.length == 3) {\nvar [_, from, to] = matches;\n// remove trailing dot on to\nif (to[to.length - 1] === \".\") {\nto = to.slice(0, -1);\n}\nreturn [to, from];\n}\n}\nreturn null;\n}\n
gitStream CM Example: extractSnykVersionBump manifest:\nversion: 1.0\nautomations:\nbump_minor:\nif:\n- {{ bump == 'minor' }}\n- {{ branch.name | includes(term=\"snyk-update\"\") }}\n - {{ branch.author | includes(term=\"snyk-update\"\") }}\nrun:\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nSnyk `minor` version bumps are approved automatically.\nbump_patch:\nif:\n- {{ bump == 'patch' }}\n- {{ branch.name | includes(term=\"snyk-update\"\") }}\n - {{ branch.author | includes(term=\"snyk-update\"\") }}\nrun:\n- action: approve@v1\n- action: merge@v1\n- action: add-comment@v1\nargs:\ncomment: |\nSnyk `patch` version bumps are approved and merged automatically.\nbump: {{ pr.description | extractSnykVersionBump | compareSemver }}\n
Download Source Code
"},{"location":"filter-function-plugins/#extractorcafindings","title":"extractOrcaFindings","text":"Extract security issues information from Orca PR reviews
Returns: Object
- Findings Findings.infrastructure_as_code: { count: null, priority: '' }, Findings.vulnerabilities: { count: null, priority: '' }, Findings.secrets: { count: null, priority: '' }, License: MIT
Object
the gitStream's PR context variable Example
{{ pr | extractOrcaFindings }}\n
Usage example, that adds lables based on Orca Secuirty findings.
Plugin Code: extractOrcaFindings/**\n * @module extractOrcaFindings\n * @description Extract security issues information from Orca PR reviews\n * @param {Object} pr - the gitStream's PR context variable\n * @returns {Object} Findings\n * Findings.infrastructure_as_code: { count: null, priority: '' },\n * Findings.vulnerabilities: { count: null, priority: '' },\n * Findings.secrets: { count: null, priority: '' },\n * @example {{ pr | extractOrcaFindings }}\n * @license MIT\n**/\nfunction getOrcaPropertyRating(lines, lineIdentifierRegex, findingsCellIndex) {\nconst matches = lines.filter(x => x.match(lineIdentifierRegex));\nconst [firstMatch] = matches;\nconst cells = firstMatch.split('|');\nconst [_, high, medium, low, info] = /\"High\"> ([\\d]+).*\"Medium\"> ([\\d]+).*\"Low\"> ([\\d]+).*\"Info\"> ([\\d]+)/\n.exec(cells[findingsCellIndex])\n.map(x => parseInt(x));\nreturn {high, medium, low, info};\n}\nmodule.exports = (pr) => {\nlet orcaObject = {\ninfrastructure_as_code: { count: null, priority: '' },\nvulnerabilities: { count: null, priority: '' },\nsecrets: { count: null, priority: '' },\n};\n// Orca comments are added as PR review\nconst orcaComment = pr.reviews.filter(x => x.commenter.includes('orca-security'));\nif (orcaComment.length) {\nconst orcaCommentArray = orcaComment[orcaComment.length - 1].content.split('\\n');\nvar priority = getOrcaPropertyRating(orcaCommentArray, /Infrastructure as Code/, 3);\norcaObject.infrastructure_as_code = {\ncount: priority.high + priority.medium + priority.low + priority.info,\npriority,\n};\nvar priority = getOrcaPropertyRating(orcaCommentArray, /Vulnerabilities/, 3);\norcaObject.vulnerabilities = {\ncount: priority.high + priority.medium + priority.low + priority.info,\npriority,\n};\nvar priority = getOrcaPropertyRating(orcaCommentArray, /Secrets/, 3);\norcaObject.secrets = {\ncount: priority.high + priority.medium + priority.low + priority.info,\npriority,\n};\n}\nreturn JSON.stringify(orcaObject);\n}\n
gitStream CM Example: extractOrcaFindings # -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in reports %}\nlabel_orca_{{ item.name }}:\nif:\n- {{ item.count > 0 }}\nrun:\n- action: add-label@v1\nargs:\nlabel: 'orca:{{ item.name }}'\n{% endfor %}\norca: {{ pr | extractOrcaFindings }}\nreports:\n- name: introduced-cves\ncount: {{ orca.vulnerabilities.count }}\n- name: iac-misconfigurations\ncount: {{ orca.infrastructure_as_code.count }}\n- name: exposed-secrets count: {{ orca.secrets.count }}\ncolors:\nred: 'b60205'\n
Download Source Code
When used, create a secret TOKEN, and add it to the workflow file, in GitHub:
jobs:\n gitStream:\n steps:\n - name: Evaluate Rules\n uses: linear-b/gitstream-github-action@v1\n env: \n CODEOWNERS: ${{ secrets.GITSTREAM_CODEOWNERS }}\n
"},{"location":"filter-function-plugins/#getcodeowners","title":"getCodeowners","text":"Resolves the PR's code owners based on the repository's CODEOWNERS file
Returns: Array.<string>
- user names License: MIT
Array.<string>
the gitStream's files context variable pr Object
the gitStream's pr context variable token string
access token with repo:read scope, used to read the CODEOWNERS file Example
{{ files | getCodeowners(pr, env.CODEOWNERS_TOKEN) }}\n
Plugin Code: getCodeowners /**\n * @module getCodeowners\n * @description Resolves the PR's code owners based on the repository's CODEOWNERS file\n * @param {string[]} files - the gitStream's files context variable\n * @param {Object} pr - the gitStream's pr context variable\n * @param {string} token - access token with repo:read scope, used to read the CODEOWNERS file\n * @returns {string[]} user names\n * @example {{ files | getCodeowners(pr, env.CODEOWNERS_TOKEN) }}\n * @license MIT\n**/\nconst { Octokit } = require(\"@octokit/rest\");\nconst ignore = require('./ignore/index.js');\nasync function loadCodeownersFile(owner, repo, auth) {\nconst octokit = new Octokit({\nrequest: { fetch },\nauth,\n});\nconst res = await octokit.repos.getContent({\nowner,\nrepo,\npath: 'CODEOWNERS'\n});\nreturn Buffer.from(res.data.content, 'base64').toString()\n}\nfunction codeownersMapping(data) {\nreturn data\n.toString()\n.split('\\n')\n.filter(x => x && !x.startsWith('#'))\n.map(x => x.split(\"#\")[0])\n.map(x => {\nconst line = x.trim();\nconst [path, ...owners] = line.split(/\\s+/);\nreturn {path, owners};\n});\n}\nfunction resolveCodeowner(mapping, file) {\nconst match = mapping\n.slice()\n.reverse()\n.find(x =>\nignore()\n.add(x.path)\n.ignores(file)\n);\nif (!match) return false;\nreturn match.owners;\n}\nmodule.exports = {\nasync: true,\nfilter: async (files, pr, token, callback) => {\nconst fileData = await loadCodeownersFile(pr.author, pr.repo, token);\nconst mapping = codeownersMapping(fileData);\nconst resolved = files\n.map(f => resolveCodeowner(mapping, f))\n.flat()\n.filter(i => typeof i === 'string')\n.map(u => u.replace(/^@/, \"\"));\nconst unique = [...new Set(resolved)];\nreturn callback(null, unique); },\n}\n
gitStream CM Example: getCodeowners # -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nsenior_review:\nif:\n- true\nrun:\n- action: explain-code-experts@v1\nargs:\ngt: 10\n- action: add-reviewers@v1\nargs:\nreviewers: {{ experts | intersection(list=owners) }}\nexperts: {{ repo | codeExperts(gt=10) }}\nowners: {{ files | codeowners(pr, env.CODEOWNERS) }}\n
Download Source Code
"},{"location":"filter-function-plugins/#isflaggeduser","title":"isFlaggedUser","text":"Returns true if the username that is passed to this function is specified in a predefined list of users. This is useful if you want gitStream automations to run only for specified users.
Returns: boolean
- Returns true if the user is specified in the flaggedUsers list, otherwise false. License: MIT
string
The GitHub username to check. Example
{{ pr.author | isFlaggedUser }}\n
Plugin Code: isFlaggedUser // Add users who you want to add to the flag list.\nconst flaggedUsers = [\"user1\", \"user2\"];\n/**\n * @module isFlaggedUser\n * @description Returns true if the username that is passed to this function is specified in a predefined list of users. \n * This is useful if you want gitStream automations to run only for specified users.\n * @param {string} Input - The GitHub username to check.\n * @returns {boolean} Returns true if the user is specified in the flaggedUsers list, otherwise false.\n * @example {{ pr.author | isFlaggedUser }}\n * @license MIT\n */\nfunction isFlaggedUser(username) {\nif (flaggedUsers.includes(username)) {\nreturn true;\n} else {\nreturn false;\n}\n};\nfunction containsString(arr, str) {\nreturn arr.includes(str);\n};\nmodule.exports = isFlaggedUser;\n// Write code to test the isflaggeduser function\nconsole.log(isFlaggedUser(\"ben\").toString());\n
gitStream CM Example: isFlaggedUser # -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\ndetect_flagged_user:\nif:\n- {{ pr.author | isFlaggedUser }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: {{ pr.author }} is a gitStream user.\n
Download Source Code
"},{"location":"filter-functions/","title":"Filter functions","text":"Filters can change the look and format of the source data, or even generate new data derived from the input values. What's important is that the original data is replaced by the result of transformations, and that's what ends up in rendered templates.
Note
Items marked with are under development and are not available yet.
"},{"location":"filter-functions/#overview","title":"Overview","text":"The following functions are supported in addition to the built-in functions provided by Nunjucks.
"},{"location":"filter-functions/#low-level-functions","title":"Low level functions","text":"Function Input Args Outputcapture
Find and return the first occurrence of a regex in the input string String regex
[Objects] difference
Given two lists, keep only items that are in the 1st list but not in the 2nd. [Objects] list
[Objects] every
Checks whether all element in the list are true
[Bool] - Bool filter
Reduce list of items into a list of same items that match the specified term [String][Object] regex
, term
, list
, attr
[String][Object] includes
Check if substring match String regex
, term
, list
Bool intersection
Given two lists, keep only items that are in both lists. [Objects] list
[Objects] map
Maps each object in a list into their specified attribute value [Object] attr
[Object] match
Maps list of items into a list of booleans that match the specified term [String][Object] regex
, term
, list
attr
[Bool] nope
Checks whether all element in the list are false
[Bool] - Bool reject
Inverse of filter
, the result list contains non-matching items [String][Object] regex
, term
, list
, attr
[String][Object] some
Checks whether at least one element in the list is true
[Bool] - Bool"},{"location":"filter-functions/#high-level-functions","title":"High level functions","text":"Function Input Args Output allDocs
Checks the list includes only documents files
- Bool allImages
Checks the list includes only images files
- Bool allTests
Checks the list includes only tests files
- Bool codeExperts
Get list of contributors based on expert reviewer model results repo
gt
, lt
[String] estimatedReviewTime
Estimated review time in minutes branch
- Integer extensions
Lists all the unique file extensions [String] - [String] extractJitFindings
Get an object with a summary of the findings found by the Jit scan pr
- Object extractSonarFindings
Get an object with a summary of the findings found by the SonarCloud scan pr
- Object explainRankByGitBlame
Short markdown text explaining rankByGitBlame results repo
gt
, lt
[String] isFirstCommit
Checks if its the author first commit in the repo repo.contributors
String Bool isFormattingChange
Checks that only formatting changed [FileDiff
] - Bool mapToEnum
return the enum value matches to the input key String Enum object Object matchDiffLines
Match every line in diff [FileDiff
] regex
, ignoreWhiteSpaces
[Bool] rankByGitActivity
Get list of contributors based on git-commit
activity repo
gt
, lt
[String] rankByGitBlame
Get list of contributors based on git-blame
results repo
gt
, lt
[String]"},{"location":"filter-functions/#named-arguments","title":"Named arguments","text":"Some functions support named arguments, many of these repeat in different functions.
term
- a single string, used as a substring to match with the matched item.
list
- a list of strings, trying to match any of the listed substrings with the matched item.
regex
- a single string, used as a regular expression with the matched item. A regular expression can be created just like JavaScript, but needs to be prefixed with r, for example, r/^foo.*/g
, for more info see Nunjucks.
attr
- a key in the element to use when doing the requested operation.
For example, the following expressions provide an identical result:
- {{ 'something' | includes(regex=r/^some.*/) }}\n- {{ 'something' | includes(term='some') }}\n- {{ 'something' | includes(list=['some']) }}\n
"},{"location":"filter-functions/#reference","title":"Reference","text":""},{"location":"filter-functions/#capture","title":"capture
","text":"Extract the first match of the regex in the input string. If no match is found, the function returns an empty string.
Argument Usage Type Description - Input String The string to find the match inregex
Input String Search term to match with the input string - Output Bool The first substring that match the provided regex For example, the following line will extract the substring \"hello wo\" from the input
{{ \"hello world\" | capture(regex=r/he.+o/) }}\n
"},{"location":"filter-functions/#difference","title":"difference
","text":"Given two lists, keep only items that are in the 1st list but not in the 2nd.
Argument Usage Type Description - Input [Objects] List of objects to inspect. list Input [Objects] List of objects to exclude. - Output [Objects] Returns a list of objects containing items that exist in one input, but not in the other."},{"location":"filter-functions/#every","title":"every
","text":"Checks whether all element in the list are\u00a0true
. In case the list of elements is empty, it will return false
.
true
when all list items are true
For example, check that all changes are in either 'src' or 'dest' directories:
{{ files | match(list=['src', 'dest']) | every }}\n
"},{"location":"filter-functions/#filter","title":"filter
","text":"Creates a shallow copy of a portion of a given list, filtered down to just the elements that match the given term. You can use either a single term, regex, or a list of terms to match with.
Argument Usage Type Description - Input [String][Object] The list of strings to match, or list of objects ifattr
is used term
regex
list
Input (either) StringString[String] Search term to match with the input items attr
Input (optional) String match a named attribute in the input object - Output [String][Object] The list with only the matching items For example, check if all changes to JavaScript files are in tests directory:
{{ files | filter(regex=r/\\.js$/) | match(regex=r/tests\\//) | every }}\n
For example, check if all changes to JavaScript files are formatting:
{{ source.diff.files | filter(attr='new_file', regex=r/\\.js$/) | isFormattingChange }}\n
"},{"location":"filter-functions/#includes","title":"includes
","text":"Determines whether a string includes a certain substring. You can use either a single term, regex, or a list of terms to match with.
Argument Usage Type Description - Input String The string you want to check for matching substringsterm
regex
list
Input (either) StringString[String] Substring term to match - Output Bool true
if search terms matches Check string matches either of the terms:
{{ 'something' | includes(list=['any', 'thing']) }}\n
"},{"location":"filter-functions/#intersection","title":"intersection
","text":"Given two lists, keep only items that are in both lists.
Argument Usage Type Description - Input [Objects] List of objects to inspect. list Input [Objects] List of objects to check for intersection. - Output [Objects] Returns a list of objects containing items that intersect between the two lists."},{"location":"filter-functions/#map","title":"map
","text":"Creates a new list populated with the values of the selected attribute of every element in the input list.
Argument Usage Type Description - Input [Object] The list of objects to map, see context for valid inputsattr
Input String Object attribute to select - Output [Object] List of the selected object attributes For example, the source.diff.files
context holds a list of FileDiff
, each has new_file
attribute. You can create a list of all the new file names by mapping to the new_file
attribute and then check if there are changes to any handler.js
file:
{{ source.diff.files | map(attr='new_file') | match(term='handler.js') | some }}\n
"},{"location":"filter-functions/#match","title":"match
","text":"Return true
for each element in the list that match the search term.
attr
used the list of objects term
regex
list
Input (either) StringString[String] Search term to match attr
Input String match a named attribute in the input object - Output [Bool] true
for every matching item For example, to check if all code changes are in the tests
directory:
{{ files | match(regex=r/tests\\//) | every }}\n
For example, to check if there are code changes with specific function call:
{{ source.diff.files | match(attr='diff', term='myFunction') | some }}\n
"},{"location":"filter-functions/#nope","title":"nope
","text":"The inverse of every
, checks whether all elements in the list are\u00a0false
. In case the list of elements is empty, it will return true
.
true
when all list items are false
For example, check that no changes in either 'src' or 'dest' directories:
{{ files | match(list=['src', 'dest']) | nope }}\n
"},{"location":"filter-functions/#reject","title":"reject
","text":"Creates a shallow copy of a portion of a given list, filtered down to just the elements that do not match the given term. You can use either a single term, regex, or a list of terms to match with.
Argument Usage Type Description - Input [String][Object] The list of strings to match, or list of objects ifattr
is used term
regex
list
Input (either) StringString[String] Search term to match with the input items attr
Input (optional) String match a named attribute in the input object - Output [String][Object] The list with only the non-matching items For example, check if all changes, but JavaScript files are in tests directory:
{{ files | reject(regex=r/\\.js$/) | match(regex=r/tests\\//') | every }}\n
For example, check if all changes except for config.json
files are formatting:
{{ source.diff.files | reject(attr='new_file', regex=r/config\\.json$/) | isFormattingChange }}\n
"},{"location":"filter-functions/#some","title":"some
","text":"Checks whether any element in the list is\u00a0true
. In case the list of elements is empty it will return false
.
true
when any of the items is true
{{ files | match(list=['src', 'dest']) | some }}\n
"},{"location":"filter-functions/#alldocs","title":"allDocs
","text":"Return true
if the input list includes only documents based on file extensions.
Doc files extensions are: md
, mkdown
, txt
, rst
, adoc
, except for requirements.txt
.
files
The list of changed files with their path - Output Bool true
if all file extensions are of docs {{ files | allDocs }}\n
In case you want to exclude more files, like all txt
under the requirements
directory, add another check:
{{ (files | allDocs) and (files | match(regex=r/requirements\\/.*\\.txt$/) | nope ) }}\n
"},{"location":"filter-functions/#allimages","title":"allImages
","text":"Return true
if the input list includes only images based on file extensions.
Image file extensions are: svg
, png
, gif
.
files
The list of changed files with their path - Output Bool true
if all file extensions are of images {{ files | allImages }}\n
"},{"location":"filter-functions/#alltests","title":"allTests
","text":"Return true
if the input list includes only tests based on the file's path and name.
To identify as test the file must include the word test
or spec
in its name or path, it is checked using this regex: [^a-zA-Z0-9](spec|test|tests)[^a-zA-Z0-9]
.
files
The list of changed files with their path - Output Bool true
if all file tests are based on name and path {{ files | allTests }}\n
"},{"location":"filter-functions/#codeexperts","title":"codeExperts
","text":"When requesting a review for a pull request, it's important to select a reviewer who has a deep understanding of the relevant code area, the domain problem, and the framework being used. This ensures that the reviewer can provide specific and informed feedback, rather than general comments that may not take into account the context in which the issue was solved.
The filter provides the list of most qualified contributors based on git-blame
and git-commit
results to determine who has been most active in the relevant code area, and then combines this information into a score between 0 and 100. The commit activity is scored higher for recent commits, which ensures that those who are actively contributing to the codebase are given higher priority as potential reviewers. The result will be limited to 2 users and shall not include the PR author.
The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame
output. When gitStream cannot map the Git user to a Git provider user it will be dropped from the output list, hence the list may contain less than 100% of the lines.
Note
The codeExperts
filter function calls gitStream app API with the repo
context to calculate the estimated review time value.
repo
The repo
context variable lt
Input Integer Filter the user list, keeping those below the specified threshold gt
Input Integer Filter the user list, keeping those above the specified threshold - Output [String] Up to 2 users, sorted by best match first (it won't include the PR author) For example:
automations:\ncode_experts:\nif: - true\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=10) }}\n
"},{"location":"filter-functions/#estimatedreviewtime","title":"estimatedReviewTime
","text":"Returns the estimated review time in minutes based on statistical model. The model uses the amount of additions and deletions statistics for each file type with additional information about the commits and base branch.
Note
The estimatedReviewTime
filter function calls gitStream app API with the branch
context to calculate the estimated review time value.
The following files are excluded when calculating this value:
Argument Usage Type Description - Inputbranch
Branch meta data - Output Integer the estimated time for review in minutes {{ branch | estimatedReviewTime }}\n
The following files are automatically excluded from the estimated review time calculation.
File type Filter type Values Data Extensionini
csv
xls
xlsx
xlr
doc
docx
txt
pps
ppt
pptx
dot
dotx
log
tar
rtf
dat
ipynb
po
profile
object
obj
dxf
twb
bcsymbolmap
tfstate
pdf
rbi
pem
crt
svg
png
jpeg
jpg
ttf
Data Regex .*dist/.*\\.js$
.*public/assets/.*\\.js$
Lock Regex .*package-lock|packages\\.lock|package)\\.json$
Lock File yarn.lock
gemfile.lock
podfile.lock
cargo.lock
composer.lock
pipfile.lock
gopkg.lock
Lock Regex .*gradle\\.lockfile$
.*lock\\.sbt$
Pipeline Regex .*ci\\.yml$
Tip
You can also filter more files, using config.ignore_files
.
extensions
","text":"Expects files
and provide a list of all unique file extensions.
files
The list of changed files with their path - Output [String] List of all unique file extensions For example, check that only one file type was changed:
{{ files | extensions | length == 1 }}\n
"},{"location":"filter-functions/#extractjitfindings","title":"extractJitFindings
","text":"Available in GitHub only
This filter is currently availalbe only in GitHub
Get an object with a summary of the findings found by Jit scan. This filter is relevant only for repos that use Jit to scan PRs
The pr
context includes all the reviews in the pull request, including the reviews written by the Jit bot, along with all the comments (conversations) to the review.
This filter reads and parses the reviews with Jit's findings, making them available for use inside the .cm
file automations.
The output is an object of the following format:
{\n\"vulnerabilities\": [{\n\"security_control\": 'string',\n\"type\": 'string',\n\"description\": 'string',\n\"severity\": 'string',\n\"summary\": 'string'\n}],\n\"metrics\": { \"HIGH\": number, \"MEDIUM\": number,\n\"LOW\": number,\n\"INFO\": number }\n}\n
Argument Usage Type Description - Input pr
The pr
context variable - Output Object The object contains the summary of Jit's scan Example of the filter output
{\n\"vulnerabilities\": [\n{\n\"security_control\": \"Static Code Analysis Js\",\n\"type\": \"Codsec.Javascriptnosql-Injection.Nosql-Injection\",\n\"description\": \"Putting request data into a mongo query can leadto a NoSQL Injection. Be sure to properly sanitize thedata if you absolutely must pass request data into a query.\",\n\"severity\": \"HIGH\",\n\"summary\": \"Jit Bot commands and options (e.g., ignore issue)\"\n},\n{\n\"security_control\": \"Secret Detection\",\n\"type\": \"Private-Key\",\n\"description\": \"Private Key\",\n\"severity\": \"HIGH\",\n\"summary\": \"Jit Bot commands and options (e.g., ignore issue)\"\n}\n],\n\"metrics\": {\n\"HIGH\": 2,\n\"MEDIUM\": 0,\n\"LOW\": 0,\n\"INFO\": 0\n}\n}\n
Assign the output to a variable
jit: {{ pr | extractJitFindings }}\n
Add a label if Jit detected secrets in the PR
automations:\nadd_bugs_label:\nif:\n- {{ jit.metrics.HIGH > 0 }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"Vulnerable code!\"\"\n
"},{"location":"filter-functions/#extractsonarfindings","title":"extractSonarFindings
","text":"Available in GitHub only
This filter is currently availalbe only in GitHub
Get an object with a summary of the findings found by the SonarCloud scan. This filter is relevant only for repos that use SonarCloud to scan PRs
The pr
context includes all the comments added to the pull request, including the comment written by the SonarCloud bot that holds a summary of its scan.
This filter reads and parses the comment with SonarCloud's scan summary and makes them available to use inside the .cm
file automations.
The output is an object of the following format:
{\n\"bugs\": {\n\"count\": number,\n\"rating\": 'string' //('A'-'E')\n},\n\"code_smells\": {\n\"count\": number,\n\"rating\": 'string' //('A'-'E')\n},\n\"vulnerabilities\": {\n\"count\": number,\n\"rating\": 'string' //('A'-'E')\n},\n\"security_hotspots\": {\n\"count\": number,\n\"rating\": 'string' //('A'-'E')\n},\n\"duplications\": number,\n\"coverage\": number\n}\n
Argument Usage Type Description - Input pr
The pr
context variable - Output Object The object contains the summary of SonCloud's scan Example of the filter output
{\n\"bugs\": {\n\"count\": 1,\n\"rating\": 'B'\n},\n\"code_smells\": {\n\"count\": 2,\n\"rating\": 'B'\n},\n\"vulnerabilities\": {\n\"count\": 2,\n\"rating\": 'E'\n},\n\"security_hotspots\": {\n\"count\": 0,\n\"rating\": 'A'\n},\n\"duplications\": 3,\n\"coverage\": 70\n}\n
Assign the output to a variable
sonar: {{ pr | extractSonarFindings }}\n
Add a label with the number of bugs if the bugs rating is other than 'A', and use mapToEnum to set its color
automations:\n# Add Bugs label\nshow_bugs_count:\nif:\n- {{ sonar.bugs.count > 0}}\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83d\udc1e x {{ sonar.bugs.count }} Bugs'\ncolor: {{ sonar.bugs.rating | mapToEnum(enum = colors) }}\ncolors:\nA: '05AA02'\nB: 'B6D146'\nC: 'EABE05'\nD: 'DF8339'\nE: 'D4343F'\n
"},{"location":"filter-functions/#explainrankbygitblame","title":"explainRankByGitBlame
","text":"This filter helps to explain the results of rankByGitBlame
, the output is in Markdown format that can be used in a PR comment.
The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame
output. Git users that could not be automatically mapped are marked with *
. To map these users, you can add user_mapping
see instructions here.
repo
The repo
context variable lt
Input Integer Filter the user list, keeping those below the specified threshold gt
Input Integer Filter the user list, keeping those above the specified threshold - Output String Explaining rankByGitBlame
results in markdown format Note
Each contributor's result is rounded down to the nearest integer, so the total may add up to less than 100%.
For example:
automations:\nthe_right_reviewer:\nif: - true\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | rankByGitBlame(gt=50) }}\n- action: add-comment@v1\nargs:\ncomment: |\n{{ repo | explainRankByGitBlame(gt=50) }}\n
Note the comment starts with |
and a new-line
as explainRankByGitBlame
generates a multiline comment.
isFirstCommit
","text":"Return true
if it's the author first commit in the repo.
repo.contributors
List of contributors in the repo - Input String The contributor name - Output Bool true
if its the first commit of the selected contributor if: - {{ repo.contributors | isFirstCommit(branch.author) }}\nrun: - action: add-comment@v1\nargs:\ncomment: \"Welcome {{branch.author}}!\"\n
"},{"location":"filter-functions/#isformattingchange","title":"isFormattingChange
","text":"Return true
if all file diffs are validated as formatting changes. This filter function works for JavaScript, TypeScript, Python, JSON, YAML and HTML.
gitStream determines formatting changes by minifying the source code for the incoming changes and the existing code and comparing them. If they are identical, this filter function returns true
. If any unsupported languages are contained in the PR, gitStream will return false
.
source.diff.files
List of file diffs - Output Bool true
if the all code changes are non functional {{ source.diff.files | isFormattingChange }}\n
"},{"location":"filter-functions/#maptoenum","title":"mapToEnum
","text":"Get the enum value matches to the input key
Argument Usage Type Description - Input String The key nameenum
Input Enum Object The enum object to which the input string should be matched - Output Object The value of the input key in the input enum object For example, set a label color according to names in the enum:
automations:\nlabel_color:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: 'Blue label'\ncolor: {{ \"blue\" | mapToEnum(enum = colors) }}\ncolors:\nred: 'FF0000'\ngreen: '00FF00'\nblue: '0000FF'\nyellow: 'FFFF00'\n
"},{"location":"filter-functions/#matchdifflines","title":"matchDiffLines
","text":"Checks diff for matching lines.
Argument Usage Type Description - Input [Object] The list of objectsregex
Input String Regex term to match with the input items, use \\\\
for \\
ignoreWhiteSpaces
Input Bool false
by default, match a named attribute in the input object caseSensitive
Input Bool true
by default, ignore case when matching terms - Output [Bool] true
for every matching object For example, to check if all the changes are of adding prints and ignore white spaces:
{{ source.diff.files | matchDiffLines(regex=r/^\\+.*console\\.log/, ignoreWhiteSpaces=true) | every }}\n
"},{"location":"filter-functions/#rankbygitactivity","title":"rankByGitActivity
","text":"Get list of contributors based on git-commit
activity.
The repo
context includes all the changed files, for each file it includes each contributor number of lines changed every week over the last 52 weeks, based on git-commit
.
These functions compare each contributor changes per week and yield an average percentage of contribution for any given file. For example, in a certain week a file had 500 line changed, 200 by a first user, while 3 other users changed 100 lines each. So the score for the first user in that week will be 40 (200/500 in %). The function then average the score for each user for the selected time period.
Then you can use the thresholds to get the right reviewer.
Argument Usage Type Description - Inputrepo
The repo
context variable weeks
Input Integer The number of last weeks to include lt
Input Integer Filter the user list, keeping those below the specified threshold gt
Input Integer Filter the user list, keeping those above the specified threshold - Output [String] The list of users based on their code score comparison Check if the branch author is a rookie
active_coders: {{ repo | rankByGitActivity(gt=50, weeks=12) }}\n
"},{"location":"filter-functions/#rankbygitblame","title":"rankByGitBlame
","text":"Get list of contributors based on git-blame
results
The repo
context includes all the changed files, for each file it includes the contributors' percentage of lines in the file, based on git-blame
.
This function sums all these percentages per user and yield an average percentage of contribution. Then you can use the thresholds to get the right reviewer.
The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame
output. When gitStream cannot map the Git user to a Git provider user it will be dropped from the output list, hence the list may contain less than 100% of the lines.
repo
The repo
context variable lt
Input Integer Filter the user list, keeping those below the specified threshold gt
Input Integer Filter the user list, keeping those above the specified threshold - Output [String] The list of users based on their code score comparison, sorted by rank - first has highest score Example of the filter output, note the output are GitHub users in the example:
[\n\"PopeyeUser\",\n\"olive_user\",\n\"BRUTUS_USER\"\n]\n
Get the most significant contributors for the PR files:
contributors: {{ repo | rankByGitBlame(gt=30) }}\n
Check if the branch author is a rookie
is_rookie: {{ repo | rankByGitBlame(lt=15) | match(term=branch.author) | some }}\n
"},{"location":"gitStream-playground/","title":"Playground","text":"Welcome to gitStream Playground! This platform allows you to thoroughly test gitStream automations before deploying them into the .cm
rule file on any GitHub pull request of your choice.
Playground
"},{"location":"gitStream-playground/#getting-started","title":"Getting Started","text":""},{"location":"gitStream-playground/#accessing-gitstream-playground","title":"Accessing gitStream Playground","text":"To access gitStream Playground, visit https://app.gitstream.cm/playground. To be able to test automations of private repository PRs, log in with your GitHub account credentials.
"},{"location":"gitStream-playground/#interface-overview","title":"Interface Overview","text":"The gitStream Playground interface consists of the following sections:
estimated_time_to_review
and safe_changes
are provided by default.Output
- shows syntax errors when the .cm
automation syntax is wrong. After running gitStream - it shows the expected result of the automation on the chosen Pull Request.Context Variables
- Shows the values of all Context variables of the chosen Pull Request.On GitHub, navigate to any pull request, copy its link, and paste it onto the \"Pull request link\" box. If the PR is part of a private repo, you must also log in to the playground with a GitHub user accessible to this repository.
"},{"location":"gitStream-playground/#running-gitstream","title":"Running gitStream","text":".cm
editor.The automation results will be shown in the \"Output\" tab at the bottom of the interface. Context Variables will be shown in the \"Context Variables\" tab.
"},{"location":"gitStream-playground/#feedback-and-support","title":"Feedback and Support","text":"For additional assistance or to provide feedback, please open an issue on our GitHub issues page
"},{"location":"github-installation/","title":"How to Setup gitStream with GitHub","text":"Install gitStream
Before you can complete the gitStream setup process, you need to install the gitStream app to your GitHub organization.
"},{"location":"github-installation/#setup","title":"Setup","text":"You can set up gitStream for a single repo or your entire GitHub organization. Select the tab below for the instructions you want.
Single RepoGitHub OrganizationSingle Repo Setup
You must implement two main components for gitStream to function for a single GitHub repo. The first is a configuration file that defines the workflow automations to execute for the repo. The second is 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 will contain a YAML configuration that determines the workflows that run on the repo, and 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 setup some basic workflow automations.
# -*- mode: yaml -*-\n# This example configuration for provides basic automations to get started with gitStream.\n# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/\nmanifest:\nversion: 1.0\nautomations:\n# Add a label that indicates how many minutes it will take to review the PR.\nestimated_time_to_review:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"{{ calc.etr }} min review\"\ncolor: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}\n# Inform PR authors when they fail to reference Jira tickets in the PR title or description.\nlabel_missing_jira_info:\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is missing a Jira ticket reference in the title or description.\nPlease add a Jira ticket reference to the title or description of this PR.\n# Post a comment that lists the best experts for the files that were modified.\nexplain_code_experts:\nif:\n- true\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10 # +----------------------------------------------------------------------------+\n# | Custom Expressions |\n# | https://docs.gitstream.cm/how-it-works/#custom-expressions |\n# +----------------------------------------------------------------------------+\ncalc:\netr: {{ branch | estimatedReviewTime }}\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\ncolors:\nred: 'b60205'\nyellow: 'fbca04'\ngreen: '0e8a16'\n
Github Actions
Once your gitStream configuration file is setup, 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\nname: gitStream workflow automation\nrun-name: |\n/:\\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}\non:\nworkflow_dispatch:\ninputs:\nclient_payload:\ndescription: The Client payload\nrequired: true\nfull_repository:\ndescription: the repository name include the owner in `owner/repo_name` format\nrequired: true\nhead_ref:\ndescription: the head sha\nrequired: true\nbase_ref:\ndescription: the base ref required: true\ninstallation_id:\ndescription: the installation id\nrequired: false\nresolver_url:\ndescription: the resolver url to pass results to\nrequired: true\nresolver_token:\ndescription: Optional resolver token for resolver service\nrequired: false\ndefault: ''\njobs:\ngitStream:\ntimeout-minutes: 5\nruns-on: ubuntu-latest\nname: gitStream workflow automation\nsteps:\n- name: Evaluate Rules\nuses: linear-b/gitstream-github-action@v1\nid: rules-engine\nwith:\nfull_repository: ${{ github.event.inputs.full_repository }}\nhead_ref: ${{ github.event.inputs.head_ref }}\nbase_ref: ${{ github.event.inputs.base_ref }}\nclient_payload: ${{ github.event.inputs.client_payload }}\ninstallation_id: ${{ github.event.inputs.installation_id }}\nresolver_url: ${{ github.event.inputs.resolver_url }}\nresolver_token: ${{ github.event.inputs.resolver_token }}\n
Success
When finished, you should have the following file structure in your repo.
.\n\u251c\u2500 .cm/\n\u2502 \u2514\u2500 gitstream.cm\n\u251c\u2500 .github/\n\u2502 \u2514\u2500 workflows/\n\u2502 \u2514\u2500 gitstream.yml\n
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 will contain 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 set up instructions for a single repo, your .cm
files should be placed in the repository's root directory.
# -*- mode: yaml -*-\n# This example configuration for provides basic automations to get started with gitStream.\n# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/\nmanifest:\nversion: 1.0\nautomations:\n# Add a label that indicates how many minutes it will take to review the PR.\nestimated_time_to_review:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"{{ calc.etr }} min review\"\ncolor: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}\n# Inform PR authors when they fail to reference Jira tickets in the PR title or description.\nlabel_missing_jira_info:\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is missing a Jira ticket reference in the title or description.\nPlease add a Jira ticket reference to the title or description of this PR.\n# Post a comment that lists the best experts for the files that were modified.\nexplain_code_experts:\nif:\n- true\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10 # +----------------------------------------------------------------------------+\n# | Custom Expressions |\n# | https://docs.gitstream.cm/how-it-works/#custom-expressions |\n# +----------------------------------------------------------------------------+\ncalc:\netr: {{ branch | estimatedReviewTime }}\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\ncolors:\nred: 'b60205'\nyellow: 'fbca04'\ngreen: '0e8a16'\n
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\nname: gitStream workflow automation\nrun-name: |\n/:\\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}\non:\nworkflow_dispatch:\ninputs:\nclient_payload:\ndescription: The Client payload\nrequired: true\nfull_repository:\ndescription: the repository name include the owner in `owner/repo_name` format\nrequired: true\nhead_ref:\ndescription: the head sha\nrequired: true\nbase_ref:\ndescription: the base ref required: true\ninstallation_id:\ndescription: the installation id\nrequired: false\nresolver_url:\ndescription: the resolver url to pass results to\nrequired: true\nresolver_token:\ndescription: Optional resolver token for resolver service\nrequired: false\ndefault: ''\njobs:\ngitStream:\ntimeout-minutes: 5\nruns-on: ubuntu-latest\nname: gitStream workflow automation\nsteps:\n- name: Evaluate Rules\nuses: linear-b/gitstream-github-action@v1\nid: rules-engine\nwith:\nfull_repository: ${{ github.event.inputs.full_repository }}\nhead_ref: ${{ github.event.inputs.head_ref }}\nbase_ref: ${{ github.event.inputs.base_ref }}\nclient_payload: ${{ github.event.inputs.client_payload }}\ninstallation_id: ${{ github.event.inputs.installation_id }}\nresolver_url: ${{ github.event.inputs.resolver_url }}\nresolver_token: ${{ github.event.inputs.resolver_token }}\n
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.
.\n\u251c\u2500 gitstream.cm\n\u251c\u2500 .github/\n\u2502 \u2514\u2500 workflows/\n\u2502 \u2514\u2500 gitstream.yml\n
gitStream will now do these two things.
When a PR is created or changed, apply or update a label that provides an estimated time to review.
When a new PR is created, comment with a list of code experts.
"},{"location":"github-installation/#next-step","title":"Next Step","text":"How gitStream Works
Read our guide: How gitStream Works to get an overview of the gitStream syntax and automation lifecycle.
"},{"location":"github-installation/#additional-resources","title":"Additional Resources","text":""},{"location":"github-installation/#required-github-permissions","title":"Required GitHub Permissions","text":"Permissions Reason Write access to dedicated gitStream app files Used to set up the gitStream workflow files Write access to code To allow gitStream to approve PRs once all conditions are met Read access to administration, issues, and metadata To get the user team membership, and branch protection settings Read and write access to actions, checks, pull requests, and workflows Trigger workflows, create and update pull requests and their checks, and modify workflow files User email Used to identify users"},{"location":"github-installation/#configure-gitstream-to-block-merges","title":"Configure gitStream to Block Merges","text":"You can configure Github to require gitStream checks to pass before PRs can be merged using branch protection rules.
Run a gitStream check before continuing
You need to run a check using your gitStream configuration at least once before it can be set as a required check. Make sure to open at least 1 PR before doing this setting.
Here are the steps to configure gitStream in your repo's branch protection rules.
settings
Code and automation
> Branches
Branch protection rules
for your desired branchRequire status checks to pass before merging
status checks in the last week for this repository
gitStream.cm
as required checkTo ensure gitStream runs on self-hosted GitHub Actions runners, follow these steps to configure it:
Configure Self-Hosted Runners with Ensure you have self-hosted runners set up for your GitHub organization or repository. Refer to the GitHub documentation on self-hosted runners and Using self-hosted runners in a workflow for detailed instructions.
Install Docker and Git on Self-Hosted Runners Make sure your self-hosted runners have Docker and Git installed. These are essential dependencies for gitStream to function properly. You can follow the official installation guides for Docker and Git.
Update GitHub Actions Configuration Open the gitStream GitHub Actions workflow file (.github/workflows/gitstream.yml
) and update the runs-on
field to specify that the gitStream job must run on self-hosted runners. For example:
jobs:\ngitStream:\nruns-on: self-hosted\n# ... other configuration ...\n
Save and Commit Save your changes to the workflow file and commit them to your repository.
Test with a Sample PR Create a sample pull request and observe gitStream's behavior. It will use the configured self-hosted runners.
Configure in your GitHub organization, and choose Uninstall \"gitStream.cm\"
Deprecated
"},{"location":"github-required-check/","title":"Github required check","text":"Deprecated
"},{"location":"gitlab-installation/","title":"How to Setup gitStream with GitLab","text":"Prerequisites
GitLab Installation Overview
gitStream automation rules are executed on behalf of the user account that is logged in when you install the gitStream service. This account must have the Maintainer
role.
We recommend creating a dedicated account for this purpose so you can more easily control access to individual repos. You can also use your professional or personal GitLab account for this, but that would result in all automations being executed under that account.
Use this account when you install gitStream
Make sure you're logged into this user account in the web browser that you use to click the installation button in step 4.
"},{"location":"gitlab-installation/#2-create-a-cm-configuration-file","title":"2. Create a CM Configuration File","text":"You can set up gitStream for a single repo or your entire GitLab organization. Select the tab below for the instructions you want.
Single RepoGitLab GroupSingle Repo Setup
Create a .cm/gitstream.cm
rules file in your repository's default branch (usually master
or main
). This file will contain a YAML configuration that determines the workflows that run on the repo, and you can name it anything you want as long as it ends in .cm
Example Configuration
Here is an example of a gitStream configuration file you can use to setup some basic workflow automations.
# -*- mode: yaml -*-\n# This example configuration for provides basic automations to get started with gitStream.\n# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/\nmanifest:\nversion: 1.0\nautomations:\n# Add a label that indicates how many minutes it will take to review the PR.\nestimated_time_to_review:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"{{ calc.etr }} min review\"\ncolor: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}\n# Inform PR authors when they fail to reference Jira tickets in the PR title or description.\nlabel_missing_jira_info:\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is missing a Jira ticket reference in the title or description.\nPlease add a Jira ticket reference to the title or description of this PR.\n# Post a comment that lists the best experts for the files that were modified.\nexplain_code_experts:\nif:\n- true\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10 # +----------------------------------------------------------------------------+\n# | Custom Expressions |\n# | https://docs.gitstream.cm/how-it-works/#custom-expressions |\n# +----------------------------------------------------------------------------+\ncalc:\netr: {{ branch | estimatedReviewTime }}\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\ncolors:\nred: 'b60205'\nyellow: 'fbca04'\ngreen: '0e8a16'\n
GitLab Group Setup
Group rules are ideal when you want to enforce consistent rules across every repo in your GitLab group. You can define them by creating a special repository named cm
in the parent group for the git repositories you want to run gitStream on. Here, you can add automation files that will apply to all repositories within that group.
Create a cm
project (repository) in your GitLab group, and create a gitstream.cm
rules file in the root directory of your cm
repository's default branch (usually master
or main
). This file will contain a YAML configuration that determines the workflows that run on your organization's repos. You can name the CM file anything you want as long as it ends in .cm
Configuration files go in the repo's root directory.
Unlike the set up instructions for a single repo, your .cm
files should be placed in the repository's root directory.
Example Configuration
Here is an example of a gitStream configuration file you can use to setup some basic workflow automations.
# -*- mode: yaml -*-\n# This example configuration for provides basic automations to get started with gitStream.\n# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/\nmanifest:\nversion: 1.0\nautomations:\n# Add a label that indicates how many minutes it will take to review the PR.\nestimated_time_to_review:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"{{ calc.etr }} min review\"\ncolor: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}\n# Inform PR authors when they fail to reference Jira tickets in the PR title or description.\nlabel_missing_jira_info:\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is missing a Jira ticket reference in the title or description.\nPlease add a Jira ticket reference to the title or description of this PR.\n# Post a comment that lists the best experts for the files that were modified.\nexplain_code_experts:\nif:\n- true\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10 # +----------------------------------------------------------------------------+\n# | Custom Expressions |\n# | https://docs.gitstream.cm/how-it-works/#custom-expressions |\n# +----------------------------------------------------------------------------+\ncalc:\netr: {{ branch | estimatedReviewTime }}\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\ncolors:\nred: 'b60205'\nyellow: 'fbca04'\ngreen: '0e8a16'\n
"},{"location":"gitlab-installation/#3-create-a-gitlab-pipeline","title":"3. Create a GitLab Pipeline","text":"Once your gitStream configuration file is setup, you need a GitLab CI configuration file to trigger gitStream automations. If you haven't already, create a cm
project (repository) in your GitLab group. It should be created in the same group or a parent group of the target repositories. Create a .gitlab-ci.yml
file in your new cm
repository's default branch (usually master
or main
) and add the following configuration:
# Code generated by gitStream - DO NOT EDIT\nstages:\n- gitstream-main\nimage: docker:latest\nservices:\n- docker:dind\nbefore_script:\n- docker login -u \"$CI_REGISTRY_USER\" -p \"$CI_REGISTRY_PASSWORD\" $CI_REGISTRY\ngitstream-job:\nstage: gitstream-main\nonly:\nvariables:\n- $GITSTREAM_MAIN_JOB\nexcept:\nvariables:\n- $GITSTREAM_BLOCK_MERGE\nscript:\n- apk update && apk add git && apk add docker\n- git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo\n- git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm\n- cd gitstream && cd repo && git fetch --all && git checkout $base_ref && git pull && ls && git checkout $head_ref && git pull && ls\n- docker pull gitstream/rules-engine:latest\n- |\ndocker run -v $CI_PROJECT_DIR/gitstream:/code \\\n-e HEAD_REF=$head_ref \\\n-e BASE_REF=$base_ref \\\n-e CLIENT_PAYLOAD=\"$client_payload\" \\\n-e RULES_RESOLVER_URL=$resolver_url \\\n-e RULES_RESOLVER_TOKEN=$resolver_token \\\n-e DEBUG_MODE=true gitstream/rules-engine:latest\n
"},{"location":"gitlab-installation/#next-step","title":"Next Step","text":"If you successfully completed these instructions, gitStream will now do these two things.
When a PR is created or changed, apply or update a label that provides an estimated time to review.
When a suggest-reviewers
label is applied to a PR, gitStream will comment with a list of code experts.
How gitStream Works
Read our guide: How gitStream Works to get an overview of the gitStream syntax and automation lifecycle.
"},{"location":"gitlab-installation/#additional-resources","title":"Additional Resources","text":""},{"location":"gitlab-installation/#required-gitlab-permissions","title":"Required GitLab Permissions","text":"The required permissions are:
Permissions Reason Read/Write API To get notified on MR changes and allow gitStream to approve MRs once all conditions are met Read repository To read and check rules over the code changes on monitored repositories Read user profile Used to identify users"},{"location":"gitlab-installation/#faq","title":"FAQ","text":"Does gitStream support the ability to block merges?\"
gitStream actions that blocks MR merge are not supported at the moment.
What is a gitStream service account?
gitStream executes rules on behalf of the user account that was used to install it. We recommend using a new dedicated account in GitLab for installing gitStream.
"},{"location":"how-it-works/","title":"How gitStream Works","text":"You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab organization. These files end with a .cm
extension, and they outline automations that will run whenever someone opens a new PR or makes changes to an existing PR.
CM files contain a combination of YAML and Jinja2 to build rules that follow an \"if this, then that\" approach to triggering and executing automations. This, combined with templating and gitStream-specific functions gives you a highly-flexible framework for building custom CM automations.
All CM files must have a section that starts with automations:
that contains one or more custom automations that will trigger for the repo. gitStream is triggered every time someone opens a new PR or changes an existing PR. Once activated, gitStream searches for applicable CM files and executes the automations that are listed inside them.
Here is an example of the basic components that are required in every CM file.
Required CM Components
Please note, this is not a valid CM automation, it is only for illustrative purposes.
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nmy_automation:\nif:\n- # Add a condition here\nrun:\n- # Add an automation here\n
Info
When editing CM files, make sure you preserve the indentation in the examples because, like YAML, gitStream uses Python-style indentation to indicate nesting.
"},{"location":"how-it-works/#automation-actions","title":"Automation Actions","text":"Automation actions specify the desired automations that should be triggered when all conditions are met. Each automation must include an if
condition and a run
section. The conditions are evaluated whenever someone creates a PR or makes changes to an existing PR; multiple conditions can be listed for a single automation, but they must all be true to invoke the actions. You can have any number of actions listed in one automation. Actions are invoked one-by-one in no particular order. PRs that are marked as Draft are ignored by default, but you can control that using explicit triggers.
Basic Automation Example
This example defines an automation named welcome_newcomer
that post a comment to welcome anyone who submits their first PR to the repo.
automations:\nwelcome_newcomer:\nif: - {{ repo.contributors | isFirstCommit(branch.author) }}\nrun: - action: add-comment@v1\nargs:\ncomment: Welcome {{branch.author}}!\n
"},{"location":"how-it-works/#context-variables-and-filter-functions","title":"Context Variables and Filter Functions","text":"Context variables are pre-defined objects that gitStream provides as the input data you will need to build your automations. These variables enable you to access information about things like the file names and paths, the person who submitted the PR, or what code was changed.
Filter functions are functions you can call and apply to variables. They are called with a pipe operator |
and can take arguments inside parentheses ( )
. The logic expressions are based on Jinja2 syntax, supported by the Nunjucks library.
Context Variable and Filter Function Example
The following statement passes the context variable files
to the filter function match
which uses an optional list of sensitive filepaths that would need to be defined later in the CM file, and returns true if any of the files match the list as indicated by the some
filter function.
{{ files | match(list=sensitive) | some }}\n
You can also apply Nunjucks logic operators to filters
Logic Operators Example
This example inverts the previous example using the keyword not
.
{{ not (files | match(list=sensitive) | some )}}\n
"},{"location":"how-it-works/#custom-expressions","title":"Custom Expressions","text":"Jinja templating makes it easy to write custom expressions that can be invoked elsewhere in your CM files. This makes it easy to reuse data, define custom criteria, and keep your configuration files cleaner so they're easier to manage.
Custom Expressions Example
This example contains two custom expressions; is:
contains a context variable and some filter functions that are invoked in the sensitive_review
automation via is.sensitive
, and sensitive directories
contains a list of directory paths that will be matched in the filter function.
automations:\nsensitive_review:\nif:\n- is.sensitive\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: 2\nis:\nsensitive: {{ files | match(list=sensitive_directories) | some }}\nsensitive_directories:\n- src/app/auth/\n- src/app/routing/\n- src/app/resources/\n
"},{"location":"how-it-works/#ignore-files-or-repos","title":"Ignore Files or Repos","text":"You can provide gitStream with a list of specific files to ignore for all automations listed in the same CM file. To do so, add a configuration:
section to the CM file that you want to apply the exclusion list to. In the configuration section, add a list of files as an argument to the ignore_files:
key.
How to Ignore Files
To ignore a list of files, add a config.ignore_files
to you CM file like this:
config:\nignore_files:\n- 'yarn.lock'\n- 'package-lock.json'\n- 'openapi.json'\n- 'ui/src/**/*Model.d.ts'\n
Similarly, if you are using gitStream for your entire git organization, you can specify repos to ignore in the gitstream.cm
file in the root directory of your cm repo.
How to Ignore Repos
config:\nignore_repositories:\n- services\n- common\n
"},{"location":"how-it-works/#configuration-priority-and-overrides","title":"Configuration Priority and Overrides","text":"You can provide any number of CM files and automations for gitStream to process and you can freely combine organization-level automations with automations inside individual repos. There are two important things you need to keep in mind when doing this.
First, when a repository defines the same automation as an organization-level rule, the repository automation will take precedence and override the organization automation. The CM file name and the automation name must both match for this to take effect because gitStream identifies all automations based on a combination of both. For example, if you have a gitstream.cm
file that contains an automation named my_automation
, gitStream will identify that as gitstream/my_automation
.
Second, no priority is given to individual automations. Instead, gitStream collects all applicable automations for a given PR and processes them all at once.
"},{"location":"how-it-works/#next-step","title":"Next Step","text":"Write your first automation.
The best way to familiarize yourself with CM syntax is to build automations, and we've covered enough info for you to start!
If you're ready to start writing automations, check out our guide: Write Your First Automation.
"},{"location":"how-it-works/#additional-resources","title":"Additional Resources","text":""},{"location":"how-it-works/#gitstream-ui","title":"gitStream UI","text":"Once you have gitStream installed and have run some automations, you can view details about them at app.gitstream.com. To view gitStream data, you will need to login with your GitHub account and have access to an organization that has run gitStream automations.
"},{"location":"how-it-works/#functional-overview","title":"Functional Overview","text":"Once gitStream is installed and configured, there are several services that will interact with your repository whenever a PR is created or changed:
Whenever a new PR is opened or an existing PR is changed, the following process occurs:
linear-b/gitstream-github-action@v1
on the repository, which looks for two things:.cm/*.cm
Here is a diagram that illustrates how things work behind the scenes:
sequenceDiagram\n autonumber\n Git Provider API->>gitStream app: PR Notification\n activate gitStream app\n gitStream app->>gitStream CI/CD script: Execute CI/CD Action\n activate gitStream CI/CD script\n gitStream CI/CD script->>gitStream agent: CM Metadata\n activate gitStream agent\n gitStream agent->>gitStream app: Applicable Automations \n deactivate gitStream agent\n deactivate gitStream CI/CD script\n loop Automations\n loop Actions\n gitStream app->>Git Provider API: Update PR\n end\n end\n deactivate gitStream app
Upon completion, gitStream will show one of the following three statuses: gitStream checks have a 10-minute timeout for fail-safe reasons. If the check exceeds this time limit, the result will be displayed as Neutral - Skipped.
"},{"location":"how-it-works/#reserved-words","title":"Reserved Words","text":"Avoid using these words when naming your automations, actions, or other components.
gitStream reserved words:
allDocs
allImages
allTests
automations
codeExperts
config
difference
estimatedReviewTime
explainCodeExperts
explainRankByGitBlame
extractJitFindings
extractSonarFindings
extensions
every
filter
includes
isFirstCommit
isFormattingChange
intersection
manifest
map
mapToEnum
match
matchDiffLines
nope
rankByGitActivity
rankByGitBlame
reject
some
Nunjucks reserved words:
abs
asyncAll
asyncEach
batch
block
call
capitalize
center
default
dictsort
dump
e
escape
extends
filter
first
float
for
forceescape
groupby
if
import
include
indent
int
join
last
length
list
lower
macro
nl2br
raw
reject
rejectattr
replace
reverse
round
safe
select
selectattr
set
slice
sort
string
striptags
sum
title
trim
truncate
upper
urlencode
urlize
verbatim
wordcount
You can add support for .cm
in your code editor, see FAQ.
If you find an issue with these docs or with gitStream itself, please search the gitStream issues page and create an issue if one doesn't already exist for your problem.
"},{"location":"plugins/","title":"Filter Function Plugins","text":"gitStream enables you to build JavaScript plugins to extend functionality for more advanced data processing and pulling data from external APIs. Use gitStream plugins to seamlessly create and integrate custom filters and other capabilities within your gitStream automations.
Example: isFlaggedUser
Here is an example of a filter function plugin that evaluates a username input against a list of specified usernames and returns true if the user is in the list.
const flaggedUsers = [\"user1\", \"user2\"];\nfunction isFlaggedUser(username) {\nif (flaggedUsers.includes(username)) {\nreturn true;\n} else {\nreturn false;\n}\n};\nmodule.exports = isFlaggedUser;\n
This creates a new isFlaggedUser
filter function that can be invoked inside gitStream CM files. For example, you can use this to enable gitStream automations to trigger only for specific PR authors. automations:\ndetect_flagged_user:\nif:\n- {{ pr.author | isFlaggedUser }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: {{ pr.author }} is a gitStream user.\n
"},{"location":"plugins/#installation","title":"Installation","text":"gitStream plugins can be installed for an entire git organization or for individual repos.
Repository Plugins Take Precedence
If two filter function plugins have the same name, the repository-level plugin overrides the organization-level plugin.
Org-LevelRepo-LevelTo use a filter function plugin in all your repositories, place it inside your cm
repository in the following location:
plugins/filters/<filterName>/index.js
Success
Once installed, you should have a directory structure that looks like this:
.\n\u251c\u2500 gitstream.cm\n\u2514\u2500 plugins/filters/<filterName>\n \u2514\u2500 index.js\n
To use a filter function plugin for a single repository, place it inside the repo in the following location:
.cm/plugins/filters/<filterName>/index.js
Success
Once installed, you should have a directory structure that looks like this:
.\n\u251c\u2500 .cm/\n\u2502 \u251c\u2500 gitstream.cm\n\u2502 \u2514\u2500 plugins/filters/<filterName>\n\u2502 \u2514\u2500 index.js\n
gitStream Community Plugins
We maintain an official list of community-contributed gitStream plugins. Click here to explore plugin examples.
"},{"location":"plugins/#usage","title":"Usage","text":"Once installed, you can call your new plugins inside CM files using the same conventions as the built in filter functions. Filters are called with a pipe operator (|
) and can take arguments. The first argument must be declared before the pipe, and all remaining arguments are passed as a set inside parenthesis. For example:
{{ \"Hello\" | plugin(\" world!\") }}\n
If the filter does not expect any arguments, you can invoke it by passing an empty string: {{ \"\" | myFilter }}\n
"},{"location":"plugins/#create-filter-function-plugins","title":"Create Filter Function Plugins","text":"gitStream plugins are based on the CommonJS module standard, a widely used pattern for structuring and importing JavaScript modules.
Supported JavaScript Dependencies
gitStream supports the following JavaScript dependencies: axios, github actions core (@actions/core), moment, lodash, octokit rest api (@octokit/rest)
No other dependencies are supported at this time. If you have recommendations for new dependencies, please open a new issue on the gitStream GitHub repo.
"},{"location":"plugins/#define-a-new-plugin","title":"Define a New Plugin","text":"Each filter function plugin must have its own unique directory inside the appropriate /filters
directory for your repo or organization. To create a new filter function, create an index.js file inside the plugin's top-level directory, all plugins must have an index.js file that serves as the primary entry point
One of the functions contained inside this file must be exported via module.exports
, using the following conventions:
Export plugins that use synchronous code:
function myFilter(author) {\nreturn \"Hello ${author}!\";\n};\nmodule.exports = myFilter;\n
When using async JavaScript in your plugin, you need two things:
callback()
containing any errors as the first argument and the result of the filter as the second.module.exports
statement that includes the properties async: true
and filter: <filterName>
with <filterName>
matching the primary function that's being exported.const myFilter = async (author, callback) => {\nconst message = { text: \"Hello ${author}!\" };\nconst error = null;\nreturn callback(error, message.text); };\nmodule.exports = {\nasync: true,\nfilter: myFilter\n}\n
Async Error Handling
Errors reported by async plugins are output to the workflow runner logs. E.g. GitHub Actions, GitLab CI, etc.
Here's how to invoke the new filter from this example:
automations:\nwelcome_author:\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: {{ pr.author | myFilter }}\n
Debugging with console.log()
Data passed to console.log()
is output in your workflow runner logs, e.g. GitHub Actions, GitLab CI, etc.
15 Minute Time Limit
gitStream actions are terminated after 15 minutes, this is a hard limit that can't be extended.
"},{"location":"plugins/#accept-arguments","title":"Accept Arguments","text":"Filter function plugins can accept any number of arguments. The first argument must be passed to the filter function via a |
operator; all subsequent arguments are passed as a set inside parenthesis.
Filter function to combine two strings
This example accepts two strings and combines them, separating by a space:
function combineStrings(str1, str2) {\nreturn str1 + \" \" + str2;\n}\nmodule.exports = combineStrings;\n
In the following invocation, \"Hello\" is passed as str1
and \"world!\" is passed as str2
{{ \"Hello\" | combineStrings(\"world!\") }}
Check out the community plugin library.
Check out the filter function plugin library to explore plugins created by the LinearB community.
"},{"location":"plugins/#contribute-to-the-community-plugin-library","title":"Contribute to the Community Plugin Library","text":"LinearB maintains a collection of community-contributed gitStream plugins. Here are the instructions for publishing a plugin as part of this library.
Create a directory for your plugin inside one of the subdirectories in plugins/filters
. The name of the directory must match the name of the exported JavaScript function. Then ensure you have all of the required files and JSDoc content outlined below.
Here is an example of a well-designed gitStream plugin.
Required Files:
module.exports
that is documented according to the JSDoc requirements outlined below.jsdoc2md
, see the instructions below.Required JSDoc tags:
@module
- This must match the name of the exported JavaScript function.@description
- A 1-2 line description that wholistically describes the functionality of the plugin.@param
- There should be one @param
tag for each argument the plugin accepts, with indicated types. Indicate which parameter is the default input parameter with the name \"Input.\"@returns
- Provide the type and a short description.@example
- Simple examples that show how to invoke the plugin.@license
- The name of the lincense contained in the LICENSE file. Here is an example of properly formatted JSDoc content:
/**\n * @module isFlaggedUser\n * @description Returns true if the username that is passed to this function is specified in a predefined list of users. \n * This is useful if you want gitStream automations to run only for specified users.\n * @param {string} Input - The GitHub username to check.\n * @returns {boolean} Returns true if the user is specified in the flaggedUsers list, otherwise false.\n * @example {{ pr.author | isFlaggedUser }}\n * @license MIT\n**/\n
How to Generate Plugin Reference Markdown
You can use jsdoc2md to convert the JSDoc content of your plugin to markdown using templates we've provided. First install jsdoc2md:
npm install -g jsdoc-to-markdown
Then, invoke the following command from inside your plugin directory:
jsdoc2md --partial ../../../docs/snippets/partials/body.hbs --partial ../../../docs/snippets/partials/sig-name.hbs --files index.js > reference.md
This should output a reference.md file that contains properly formatted markdown based on the JSDoc contents of your plugin.
"},{"location":"quick-start/","title":"Write Your First gitStream Automation","text":"This article provides Continuous Merge (CM) examples to help you start customizing gitStream automations to meet the needs of your team.
"},{"location":"quick-start/#approve-simple-changes","title":"Approve Simple Changes","text":"Changes to documentation, testing, and code formatting are often safe enough that there is little to no risk in letting an individual contributor merge those changes without needing to distract other people on their team to meet organization-wide requirements for multiple reviews on PRs. A good first Continuous Merge (CM) automation to implement is one that labels and approves changes to resources that could be considered safe changes.
This example uses the filter functions allDocs
, allTests
, isFormattingChange
and match
to detect changes that should be safe to merge with minimal review. It then uses the add-label
automation action to apply a safe-changes label and the approve
automation action to provide an approval review.
Label and Approve Simple Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nsafe_changes:\nif:\n- {{ is.docs or is.tests or is.asset or is.formatting }}\nrun: - action: add-label@v1\nargs:\nlabel: 'safe-changes'\n- action: approve@v1\nis:\ndocs: {{ files | allDocs }}\ntests: {{ files | allTests }}\nasset: {{ files | match(regex=r/\\.(png|svg|gif|css)$/) | every }}\nformatting: {{ source.diff.files | isFormattingChange }}\n
Test Your Automation in Dry Run Mode
gitStream includes a dry-run mode that let's you test your automations on your desired repo without pushing significant code, documentation, or other changes to the repo.
Learn more in our guide: How to Test Your Automations.
"},{"location":"quick-start/#find-reviewers-for-common-changes","title":"Find Reviewers for Common Changes","text":"Selecting the right reviewer for your PR is crucial to ensure that your changes are thoroughly reviewed and that any issues are identified and addressed before they are merged into the main codebase.
This example uses the codeExperts
filter function to identify the most qualified contributors based on their activity in the repo. It then assigns those individuals as reviewers on the PR with the add-reviewers
automation action and posts a comment that lists the code experts via the explain-code-experts
automation action.
Identify and Assign Code Experts for Reviews
This example uses the codeExperts filter function to identify the people who have the most expertise in the relevant code, assigns them as reviewers, and provides a comment that explains how those people were selected.
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nassign_code_experts:\n# Triggered when someone applies a suggest-reviewer label to a PR.\nif: - {{ pr.labels | match(term='suggest-reviewer') | some }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=10) }}\n- action: explain-code-experts@v1 args:\ngt: 10
"},{"location":"quick-start/#enforce-review-policies-for-critical-changes","title":"Enforce Review Policies for Critical Changes","text":"Complex and sensitive PRs often require more nuanced and complex review processes that bring in outside teams of experts to review code changes. gitStream makes it easy to set up custom review policies to keep teams align across your organization. This example contains two automations that implement custom review policies for specific parts of a codebase.
First, the security_review
automation uses the require-reviewers
automation action to add the security team from the git organization as reviewers on PRs that affect the auth
directory of the repo. This action accepts a reviewers:
argument that contains a list of teams or individual users; you will need to change this value to match your organization and users.
Second, the double_review
automation forces any changes to the agent
directory to require a review from two people using the set-required-approvals
automation action.
Enforce Review Policies
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nsecurity_review:\nif:\n- {{ files | match(regex=r/auth\\//) | some }}\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [my_organization/security]\n- action: add-reviewers@v1\nargs:\nreviewers: [my_organization/security]\ndouble_review:\nif:\n- {{ files | match(regex=r/agent\\//) | some }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n
"},{"location":"quick-start/#next-step","title":"Next Step","text":"Take a Look at the Quickstart Examples
You're ready to browse our CM example library to build more automations for your repo. We have examples that help provide context to PRs with labels, assign reviewers based on custom criteria, manage security requirements, and more.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#i-cant-see-any-action-running","title":"I can't see any action running","text":""},{"location":"troubleshooting/#did-you-install-gitstream-in-your-repo","title":"Did you install gitStream in your repo?","text":"Check that you see gitStream app on repository's Settings > GitHub apps:
In case you don't see it, visit the marketplace and install it for free: https://github.com/marketplace/gitstream-by-linearb
"},{"location":"troubleshooting/#did-you-set-the-workflow-files-correctly","title":"Did you set the workflow files correctly?","text":"Check you have placed these two files in your repository with these exact names:
gitstream.cm
in the cm
repo, (for org level installs), or .cm/gitstream.cm
on all other repositories.github/workflows/gitstream.yml
These files must be committed to the repository default branch (usually master
or main
). Notice that the action will not run until these files are found on the default branch.
Check that you see \"gitStream workflow automation\" in the Action section in your repository:
Next, if you see failed action, check out the details:
Some organization limit which actions can run, in that case in the repository settings you should enable it:
Also, add
linear-b/gitstream-github-action@v1,*/*/.github/workflows/gitstream.yml*\n
to the Allow specified actions and reusable workflows list, if it is shown. "},{"location":"troubleshooting/#using-org-level-did-you-enable-gitstream-for-your-cm-repo","title":"Using org level? Did you enable gitStream for your cm
repo","text":"Make sure you have added the cm
repo to the repos gitStream should run on
gitStream automations won't trigger for PRs that are in Draft mode.
"},{"location":"troubleshooting/#i-see-gitstream-workflow-file-not-found-error","title":"I see 'gitStream workflow file not found' error","text":"This error indicates that gitStream is unable to locate the file .github/workflows/gitstream.yml
. The tool first searches for this file in the cm
repository and then in the PR's repository. If the CI file is not found, this error message is displayed. To resolve this issue, ensure that your setup is correct and that the specified file exists in your repository.
For example, when using the set-required-approvals
action, gitStream can ensure the PR got enough approvals before it can be merged. gitStream does that by running as a check and marking the check conclusion as failed. In order for the PR to be blocked, gitStream should be set as a required check in the repo: instructions here.
In order for gitStream to be listed as a required check, it needs to be triggered at least once in that repo. First create a new PR so gitStream is triggered.
Check it under repository's Settings > Branches:
"},{"location":"troubleshooting/#i-dont-want-gitstream-to-run-on-prs-that-was-generated-by-a-bot","title":"I don't want gitStream to run on PRs that was generated by a bot","text":"You can edit the .github/workflows/gitstream.yml
and uncomment the if
line, you can edit and replace the bot name with the bot name you want to ignore (dependabot[bot]
in the example below):
jobs:\ngitStream:\ntimeout-minutes: 5\n# uncomment this condition, if you don't want any automation on dependabot PRs\nif: github.actor != 'dependabot[bot]'\nruns-on: ubuntu-latest\nname: gitStream workflow automation\nsteps:\n- name: Evaluate Rules\nuses: linear-b/gitstream-github-action@v1\n
"},{"location":"troubleshooting/#gitstream-fails-and-i-dont-understand-why","title":"gitStream fails and I don't understand why","text":"gitStream check run can fail from different reasons, and these are shown in the check result.
"},{"location":"troubleshooting/#missing-workflow-file","title":"Missing workflow file","text":"When it says gitStream.cm Skipped \u2014 gitStream workflow file not found
, it means that the GitHub action was not found, check again that you have this file in your repository root: .github/workflows/gitstream.yml
, see instructions on GitHub installation.
Clicking the Details
button will show more information and context.
You can add this automation to see details on context variable.
"},{"location":"troubleshooting/#how-can-i-debug-expressions-and-see-their-content","title":"How can I debug expressions and see their content?","text":"You can dump any context value to the PR comment. For example, to see the list of changed files, use:
automations:\nshow_changed_files:\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nFILES DUMP {{ files | dump | safe }}\nJS FILES DUMP {{ files | filter(regex=r/\\.js$/) | dump | safe }}\n
Download and add to your repo .cm directory
"},{"location":"troubleshooting/#gitstream-fails-with-syntax-error-after-adding-new-rules","title":"gitStream fails with syntax error after adding new rules","text":"IntelliJ IDEA has automatic code styling for YAML that can break the .cm
syntax, check the following Settings/Preferences | Editor | Code Style | YAML --> Spaces | Code braces and make sure it is unchecked.
VS Code YAML plugin by Red Hat extension [vscode-yaml](https://github.com/redhat-developer/vscode-yaml)
has automatic code styling for YAML that can break the .cm
syntax, make sure you disable bracketSpacing
{\n\"yaml.format.bracketSpacing\": false,\n}\n
"},{"location":"troubleshooting/#not-here","title":"Not here?","text":"Create a new issue in the project's issues
"},{"location":"automations/automation-library/","title":"gitStream Automation Library","text":"This library of gitStream examples is meant to serve as a starting point for your automation. We encourage you to customize them for your project and organization.
How to use these examples.
These examples are all 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 configurations to ensure they work properly.
missing-tests
label to any PRs that lack updates to tests.These examples help you label PRs where Generative AI was used to generate code.
These examples help you follow your team's security best practices.
LinearB
"},{"location":"automations/automation-library/#github-gitlab","title":"GitHub / GitLab","text":":: GitHub Actions
:: GitHub Copilot
PR Labels
Branch Management
PR Reviews
"},{"location":"automations/automation-library/#security","title":"Security","text":"Jit
SonarCloud
Dependabot
"},{"location":"automations/automation-library/#project-management","title":"Project Management","text":"Jira
Asana
Shortcut
Azure Boards
"},{"location":"automations/automation-library/#languages","title":"Languages","text":"JavaScript
Go
Python
Java
Ruby
HTML/CSS
Rust
"},{"location":"automations/automation-library/#documentation","title":"Documentation","text":"Swimm
Javadoc
JSDoc
RDoc
Godoc
"},{"location":"automations/automation-library/#other","title":"Other","text":"Terraform
"},{"location":"automations/automation-library/#utilities","title":"Utilities","text":"These examples provide useful components to use in other automations. These aren't intended to be used on their own; instead they act as a reference point for improving other automations.
Have a great idea for an automation that should be included in this library?
Submit your configuration on GitHub. We'll recognize your contribution publicly (if you want) and might even send you some special swag for your contribution.
"},{"location":"automations/additional-review-for-large-pr/","title":"Additional Review for Large PRs","text":"Require 2 reviewers for PRs that have more than 10 changed files in the src directory and the estimated time to review is 30 or more minutes.
Configuration Description
Conditions (all must be true):
src
directory.Automation Actions:
Additional Review for Large PRs
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nadditional_review_for_large_pr:\nif:\n- {{ branch | estimatedReviewTime >= 30 }}\n- {{ files | length >= 10 }}\n- {{ files | match(regex=r/src\\//) | some }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is a large change and requires 2 reviews.\n
Download this example as a CM file. "},{"location":"automations/additional-review-for-large-pr/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/approve-safe-changes/","title":"Approve Safe Changes","text":"Automatically approve PRs that change docs, tests, and other safe assets.
Configuration Description
Conditions (all must be true):
Automation Actions:
safe-change
labelApprove Safe Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nsafe_changes:\n# Triggered for any changes that only affect formatting, documentation, tests, or images\nif:\n- {{ is.formatting or is.docs or is.tests or is.image }}\n# Apply a safe change label, approve the PR and explain why in a comment.\nrun: - action: add-label@v1\nargs:\nlabel: 'safe-change'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is considered a safe change and has been automatically approved.\n# These custom expressions are used in the safe_changes automation\nis:\nformatting: {{ source.diff.files | isFormattingChange }}\ndocs: {{ files | allDocs }}\ntests: {{ files | allTests }}\nimage: {{ files | allImages }}\n
Download this example as a CM file. "},{"location":"automations/approve-safe-changes/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/approve-swimm/","title":"Index","text":"This file has moved: /docs/automations/integrations/swimm/approve-swimm
"},{"location":"automations/approve-team-by-directory/","title":"Approve Trusted Team","text":"Automatically approve low-risk PRs from trusted teams.
Configuration Description
Conditions (all must be true):
docs
directorytech-writers
team.Automation Actions:
Approve Expert Team
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_team_by_directory:\n# Triggered for PRs that only include changes to files inside the docs directory,\n# and that are authored by someone on the tech-writers team.\nif:\n- {{ files | match(regex=r/docs\\//) | every }}\n- {{ pr.author_teams | match(term='tech-writers') }}\nrun: - action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nDocs changes from the tech-writers team are automatically approved.\n
Download this example as a CM file. "},{"location":"automations/approve-team-by-directory/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/approve-tests/","title":"Approve test changes","text":"Label and approve PRs that only include tests, and post an explanation comment.
Configuration Description
Conditions (all must be true):
Automation Actions:
Approve Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_tests:\nif:\n# Triggered for PRs that only include changes to tests\n- {{ files | allTests }}\nrun: - action: add-label@v1\nargs:\nlabel: 'tests-only'\n- action: add-comment@v1\nargs:\ncomment: |\nThis merge has been automatically approved because it only contains changes to tests.\n- action: approve@v1\n
Download this example as a CM file. "},{"location":"automations/approve-tests/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/approve-tiny-changes/","title":"Approve Tiny Changes","text":"Approve single-line changes to a single file.
Configuration Description
Conditions (all must be true):
Automation Actions:
single-line
label.name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_tiny_change:\n# Triggered for PRs that contain one file and one line.\nif:\n- {{ is.one_file and is.one_line }}\nrun:\n- action: add-label@v1\nargs:\nlabel: 'single-line'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it is only a single line\nchanges:\n# Sum all the lines added in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n# Sum all the line removed in the PR\ndeletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}\nis:\none_file: {{ files | length == 1 }}\none_line: {{ changes.additions - changes.deletions <= 1 }}\n
Download this example as a CM file. "},{"location":"automations/approve-tiny-changes/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/assign-reviewers-by-directory/","title":"Assign Reviewers by Directory","text":"Automatically assign code reviewers based on directory structure. Optionally, you can substitue require-reviewers
for add-reviewers
to make review from the specified teams and individuals mandatory.
Configuration Description
Conditions (all must be true):
src/ui
directory.Automation Actions:
my-teamate
and a team named my-organization/ui-team
as reviewers. These should be customized to match your organization.Assign Reviewers by Directory
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_ui:\n# Triggered for PRs that contain any changes to JavaScript files inside the `src/ui` directory.\nif:\n- {{ files | match(regex=r/src\\/app\\/auth\\/.*/) | some}}\n# Add a specified user and team as reviewers.\n# Customize the reviewers to match your organization\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [my-teamate, my-organization/security]\n- action: add-comment@v1\nargs:\ncomment: |\nThe Security team has automatically been added for review because this PR contains changes to components inside `/src/app/auth`\n
Download this example as a CM file."},{"location":"automations/assign-reviewers-by-directory/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/assign-team-members-as-reviewers/","title":"Assign team members as reviewers","text":"Assign PR reviewer based on the owner team membership.
You can also omit the | first
filter to assign all teams the owner is member of.
name
\n
Download this example as a CM file. "},{"location":"automations/assign-team-members-as-reviewers/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/change-deprecated-components/","title":"Change Deprecated Components","text":"Request changes when a PR includes one or more deprecated components.
Configuration Description
Conditions (all must be true):
Automation Actions:
deprecated-component
label to the PRChange Deprecated Components
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Request changes when a PR includes deprecated components.\n# This requires the `item` custom expression found at the bottom of this file.\n{% for item in deprecated %}\n# Automation names must be unique, so this adds an iterator index to each instance\nreview_deprecated_component_{{ item.old }}:\n# Triggered when any of the modified files use a deprecated component\nif:\n- {{ source.diff.files | matchDiffLines(regex=item.regex) | some }}\n# Apply a deprecated-component label, request changes, and post a comment with an explanation.\nrun:\n- action: add-label@v1\nargs:\nlabel: 'deprecated-component'\ncolor: '#FF0000'\n- action: request-changes@v1\nargs:\ncomment: |\n`{{ item.old }}` component is deprecated, use `{{ item.new }}` instead\n{% endfor %}\n# These are the deprecated files that are evaluated in catch_deprecated_components\ndeprecated:\n- regex: r/oldAPI/\nold: oldAPI\nnew: newAPI\n- regex: r/anotherOldAPI/\nold: anotherOldAPI\nnew: anotherNewAPI\n
Download this example as a CM file."},{"location":"automations/change-deprecated-components/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/change-missing-lambda-field/","title":"Change Missing Lambda Field","text":"If a PR creates a new Lambda function, but lacks a description field, gitStream will request changes and post a comment that explains why.
Configuration Description
Conditions (all must be true):
Automation Actions:
lambda-missing-field
label to the PR.Change Missing Lambda Field
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Request changes when required Lambda information is missing from the PR.\ncatch_missing_lambda_info:\n# Triggered for new Lambda functions that are missing a description field.\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/LambdaFunction/) | some }}\n- {{ source.diff.files | matchDiffLines(regex=r/description:/) | nope }}\n# Apply the lambda-missing-field label and request changes to the PR.\nrun:\n- action: add-label@v1\nargs:\nlabel: 'lambda-missing-field'\ncolor: '#FF0000'\n- action: request-changes@v1\nargs:\ncomment: |\nNew `LambdaFunction` must have `description:` field.\n
Download this example as a CM file."},{"location":"automations/change-missing-lambda-field/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/close-wrong-team-by-directory/","title":"Close Wrong Team by Directory","text":"Close PRs to a specified directory if the PR author is not on an approved team.
Configuration Description
Conditions (all must be true):
/src/views
. Customize this value for your project.ui
team. Customize this value for your organization.Automation Actions:
Close Wrong Team by Directory
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Close PRs to restricted sections of the codebase if the PR author isn't on the correct team. \nclose_wrong_team_by_directory:\n# Triggered when someone who isn't on the `ui` team submits a PR to change files inside /src/views\nif:\n- {{ files | match(regex=r/src\\/views/) | some }}\n- {{ pr.author_teams | match(term='ui') | nope }}\n# Close the PR and post a comment explaining the next step.\nrun:\n- action: add-comment@v1\nargs: comment: Please contact a member of the `ui` team if you need to make changes to files in `src/views`\n- action: close@v1\n
Download this example as a CM file."},{"location":"automations/close-wrong-team-by-directory/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/asana/label-missing-asana/","title":"Label Missing Asana","text":"Automatically label PRs that are missing references to Asana resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Asana Link
labelLabel Missing Asana
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_asana:\nif:\n- {{not (has.asana.ticket_in_title or has.asana.ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Asana Link\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated Asana resource.\nhas:\nasana:\nticket_in_title: {{ pr.title | includes(regex=r/asana-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/app\\.asana.\\com\\/(\\d+)\\/(\\d+)\\/(\\d+)\\/(\\d+)\\/(\\d+)/) }}\ncolors:\nred: 'b60205'\n
Download this example as a CM file."},{"location":"automations/integrations/asana/label-missing-asana/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/asana/link-asana/","title":"Automatically Link PRs to Related Asana Cards","text":"Provide automatic links to Asana cards that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Asana Card
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nprovider: asana\n# Configure this to match your organization. It is used in tracker.asana.baseurl.\nasanaProject: 1234\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_asana:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\nasana:\nbaseurl: https://app.asana.com/0/[asanaProject]/0/\npattern: r/asana-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"automations/integrations/asana/link-asana/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/azure-boards/label-missing-azure-boards/","title":"Label Missing Azure Boards Info","text":"Automatically label PRs that are missing references to Azure Boards resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Azure Boards Link
labelLabel Missing Azure Boards
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_azure:\nif:\n- {{not (has.azure.ticket_in_title or has.azure.ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Azure Boards Link\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated resource in Azure Boards.\nhas:\nazure:\nticket_in_title: {{ pr.title | includes(regex=r/(\\w+)-(\\w+)-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/(dev\\.azure\\.com|(\\w+)\\.visualstudio\\.com)\\/(\\w+)\\/(\\w+)\\/_workitems\\/edit\\/(\\d+)/) }}\ncolors:\nred: 'b60205'\n
Download this example as a CM file."},{"location":"automations/integrations/azure-boards/label-missing-azure-boards/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/azure-boards/link-azure-boards/","title":"Automatically Link PRs to Related Azure Boards Resources","text":"Provide automatic links to Azure Boards resources that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Azure Boards Resource
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Configure these to match your organization.\nprovider: azure\n# The name of your Azure organization\norgName: org\n# The name of your Azure project\nazureProject: my_project\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_azure_boards:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\nazure:\nbaseurl: https://dev.azure.com/[orgName]/[azureProject]/_workitems/\npattern: r/(\\w+)-(\\w+)-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"automations/integrations/azure-boards/link-azure-boards/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/copilot/flag-copilot-pr/","title":"Automatically Label GitHub Copilot PRs","text":"Automatically apply labels to PRs that are assisted by GitHub Copilot. You can apply labels based on a known list of Copilot users, PR tags, or by prompting the PR author to indicate if they used Copilot.
Label by Known UsersLabel by TagLabel by PromptAutomatically apply labels to PRs that are created by known users of generative AI coding tools.
Configuration Description
Conditions:
Automation Actions:
\ud83e\udd16 Copilot
label to the PRLabel by Contributors
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_genai:\n# For all PRs authored by someone who is specified in the genai_contributors list\nif:\n- {{ pr.author | match(list=genai_contributors) | some }}\n# Apply a label indicating the user has adopted Copilot\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\ngenai_contributors:\n- username1\n- username2\n- etc\n
Download this example as a CM file. Look for a specific tag in the PR title, description, comments or commit messages and if found add a label to the PR
Configuration Description
Conditions:
#copilot#
tag is found in any of the PR title, description, comments or commit messages for commits in the PRAutomation Actions:
\ud83e\udd16 Copilot
label to the PRLabel Copilot by Tag
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_copilot:\n# Detect PRs that contain the text '#copilot#' in the title, description, comments, or commit messages\nif:\n- {{ copilot_tag.pr_title or copilot_tag.pr_desc or copilot_tag.pr_comments or copilot_tag.commit_messages }}\n# Apply a label indicating the user has adopted Copilot\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\ncopilot_tag:\npr_title: {{ pr.title | includes(regex=r/#copilot#/) }}\npr_desc: {{pr.description | includes(regex=r/#copilot#/) }}\npr_comments: {{ pr.comments | map(attr='content') | match(regex=r/#copilot#/) | some }}\ncommit_messages: {{ branch.commits.messages | match(regex=r/#copilot#/) | some }}\n
Download this example as a CM file. Prompt PR authors to indicate if they used Copilot for the PR and automatically label the PR if they did. This requires two separate automation files to handle posting the prompt and labeling accordingly.
Configuration Description
Conditions:
Automation Actions:
Ask the PR author about Copilot usage.
-*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\nautomations:\ncomment_copilot_prompt:\n# Post a comment for all PRs to prompt the PR author to indicate whether they used Copilot to assist coding in this PR\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nPlease mark whether you used Copilot to assist coding in this PR\n- [ ] Copilot Assisted\n- [ ] Not Copilot Assisted\n
Download this example as a CM file. Configuration Description
Conditions:
Automation Actions:
\ud83e\udd16 Copilot
label to the PR Label PRs where the user indicated Copilot usage
-*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- comment_added\n- commit\n- merge\nautomations:\n# You should use this automation in conjunction with comment_copilot_prompt.cm\nlabel_copilot_pr:\n# If the PR author has indicated that they used Copilot to assist coding in this PR, \n# apply a label indicating the PR was supported by Copilot\nif:\n- {{ pr.comments | filter(attr='commenter', term='gitstream-cm') | filter (attr='content', regex=r/\\- \\[x\\] Copilot Assisted/) | some}}\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\n
Download this example as a CM file. "},{"location":"automations/integrations/dependabot/approve-dependabot/","title":"Approve and Merge Dependabot Changes","text":"Approve PRs from Dependabot
Conditions (all must be true):
Automation Actions:
approved-dependabot
label to the PRApprove Dependabot
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_dependabot:\nif:\n- {{ branch.name | includes(term=\"dependabot\") }}\n- {{ branch.author | includes(term=\"dependabot\") }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: \"approved-dependabot\"\n- action: merge@v1\nargs:\nwait_for_all_checks: true\nsquash_on_merge: true\n
Download this example as a CM file. "},{"location":"automations/integrations/github-actions/dispatch-github-action/","title":"Dispatch GitHub Actions","text":"Automatically trigger GitHub Actions based on PR content like changed resources, source or target branch, slash commands, and more.
By BranchUsing LabelsBy Modified ResourcesConfiguration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions by Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\nautomations:\n{% for item in pipelines %}\n# Change pr.target to branch.name if you want to trigger on the source branch rather then the target branch.\ndispatch_github_action_{{ item.name }}:\nif:\n- {{ pr.target | includes(term=item.branch_prefix) }}\nrun:\n- action: run-github-workflow@v1\nargs:\nworkflow: .github/workflows/{{ item.workflow }}\ncheck_name: {{ item.name }}\n- action: add-label@v1\nargs:\nlabel: {{ item.label }}\n{% endfor %}\npipelines:\n- name: mobile_ci\nlabel: Mobile CI branch_prefix: 'mobile-'\nworkflow: mobile.yml\n- name: backend_ci\nlabel: Backend CI branch_prefix: 'backend-'\nworkflow: 'backend.yml'\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Using Labels
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- label_added\n- label_removed\nautomations:\n{% for item in pipelines %}\ndispatch_github_action_{{ item.name }}:\nif:\n- {{ pr.labels | match(term=item.label) | some }}\nrun:\n- action: run-github-workflow@v1\nargs:\nworkflow: .github/workflows/{{ item.workflow }}\ncheck_name: {{ item.name }}\n{% endfor %}\npipelines:\n- name: mobile-ci\nlabel: Mobile CI workflow: mobile.yml\n- name: backend-ci\nlabel: Backend CI workflow: 'backend.yml'\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\nautomations:\n{% for item in pipelines %}\ndispatch_github_action_{{ item.name }}:\nif:\n- {{ files | match(list=item.resources) | some }}\nrun:\n- action: run-github-workflow@v1\nargs:\nworkflow: .github/workflows/{{ item.workflow }}\ncheck_name: {{ item.name }}\n- action: add-label@v1\nargs:\nlabel: {{ item.label }}\n{% endfor %}\npipelines:\n- name: mobile-ci\nlabel: Mobile CI resources:\n- 'src/android/'\n- 'src/ios/'\nworkflow: mobile.yml\n- name: backend-ci\nlabel: Backend CI resources:\n- 'src/api/'\n- 'src/services'\nworkflow: 'backend.yml'\n- name: frontend-ci\nlabel: Frontend CI\nresources:\n- 'src/app/'\nworkflow: 'frontend.yml'\n
Download this example as a CM file. "},{"location":"automations/integrations/github-actions/dispatch-github-action/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/github-actions/skip-github-action/","title":"Skip Required GitHub Actions","text":"Automatically skip GitHub Actions based on branch names, modified resource, slash commands, and more.
Prerequisite Config for Required Statuses
If you want to skip a required status check, you will need to make sure that your branch protection is configured to allow gitStream to bypass status check requirements.
By BranchUsing LabelsBy Modified ResourceConfiguration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions by Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\n# Optionally, you can change pr.target to branch.name \n# if you want to trigger based on the source branch name rather then the target branch name.\nautomations:\nskip_github_action_branch:\nif:\n- {{ pr.target | includes(term='release') }}\nrun:\n- action: add-github-check@v1\nargs:\ncheck_name: staging-ci\nconclusion: skipped\n- action: add-comment@v1\nargs:\ncomment: |\n[gitStream](https://docs.gitstream.cm) automatically skipped staging CI pipelines because this PR targets the release branch.\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Use Labels to Automatically Skip GitHub Actions
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- label_added\n- label_removed\nautomations:\nskip_github_action_label:\nif:\n- {{ pr.labels | match(term='experimental') | some }}\nrun:\n- action: add-github-check@v1\nargs:\ncheck_name: production-ci\nconclusion: skipped\n- action: add-comment@v1\nargs:\ncomment: |\n[gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this is labeled for experimental release.\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\nautomations:\nskip_github_action_resource:\nif:\n- {{ files | match(term='docs/') | every }}\nrun:\n- action: add-github-check@v1\nargs:\ncheck_name: release-ci\nconclusion: skipped\n- action: add-github-check@v1\nargs:\ncheck_name: mobile-ci\nconclusion: skipped\n- action: add-comment@v1\nargs:\ncomment: |\n[gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this PR only contains docs changes.\n
Download this example as a CM file. "},{"location":"automations/integrations/github-actions/skip-github-action/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/godoc/review-godoc/","title":"Review Godoc Changes","text":"Approve PRs that only contain changes to Godoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
\ud83d\udcd3 Godoc Only
labelReview Godoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Assign PRs that only affect godocs to the technical writing team and add docs label\nreview_godoc:\nif:\n- {{ source.diff.files | match(attr='diff', regex=r/^\\/\\/.*/) | every }}\n- {{ files | extensions | match(regex=r/go/) | every }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3godoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [org/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"automations/integrations/godoc/review-godoc-large/","title":"Review Godoc for Large Changes","text":"Require more extensive reviews for large Golang changes that lack Godoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\u26a0\ufe0f Missing Godoc
LabelReview Godoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Golang changes that lack Godoc updates.\nreview_godoc_large:\nif:\n- {{ changes.additions > 100}}\n- {{ source.diff.files | matchDiffLines(regex=r/^\\/\\/.*/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Godoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to Golang classes, but is missing updates to Godoc. Please double check for any necessary Godoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/godoc/review-godoc-new-class/","title":"Require Godoc for New Golang Classes","text":"Require Godoc for all new Golang classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Godoc
label.Enforce Godoc for New Golang Classes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_godoc_new_class: if: - {{ is.go and is.new }} - {{ source.diff.files | match(attr='diff', regex=r/\\/*[\\s\\S]*?\\//) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing godoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | godoc is required for all Golang classes. Please add godoc to all new classes in this PR.\nis:\ngo: {{ files | extensions | match(regex=r/go/) | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/javadoc/review-javadoc/","title":"Review Javadoc Changes","text":"Unblock PRs that only change Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
org/tech-writers
team for optional review. \ud83d\udcd3 Javadoc Only
labelReview Javadoc Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Assign PRs that only affect JavaDocs to the technical writing team and add docs label\nreview_javadoc:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\b(public|protected|private|static|final|synchronized)?\\s+\\w+\\s+\\w+\\s*\\(([^)]*)\\)\\s*\\{/) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3 Javadoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [org/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"automations/integrations/javadoc/review-javadoc-input-parameters/","title":"Review Java Input Parameters for Javadoc Changes","text":"If a PR modifies the input parameters for a Java method, but not the associated Javadocs, notify reviewers to check for Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Javadoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_javadoc_input_parameters: if: - {{ source.diff.files | matchDiffLines(regex=r/\\*\\s@param/) | nope }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\b(public|protected|private|static|final|synchronized)?\\s+\\w+\\s+\\w+\\s*\\(([^)]*)\\)\\s*\\{/) | some }}\nrun:\n- action: add-comment@v1\nargs: comment: | This PR modifies method input parameters, but is missing Javadoc changes. Please check to ensure no Javadoc changes are necessary.\n
Download this example as a CM file."},{"location":"automations/integrations/javadoc/review-javadoc-large-change/","title":"Review Javadoc for Large Changes","text":"Require more extensive reviews for large Java changes that lack Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/tech-writers
team.\u26a0\ufe0f Missing Javadoc
LabelReview Javadoc for Large Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Java changes that lack Javadoc updates.\nreview_javadoc_large:\nif:\n- {{ changes.ratio > 25}}\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Javadoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n# Sum all the line removed in the PR\ndeletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}\n# Calculate the ratio of new code\nratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/javadoc/review-new-class-javadoc/","title":"Enforce Javadoc Requirements for New Classes","text":"Automatically request changes when someone creates a new Java class that lacks Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Javadoc
label.Review Javadoc Requirements for New Classes
manifest:\nversion: 1.0\nautomations:\nreview_new_class_javadoc:\n# Triggered for new Java files that lack Javadoc content.\nif:\n- {{ is.java and is.new }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Javadoc\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: | This PR creates new Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.\nis:\njava: {{ files | extensions | match(term='java') | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/jira/label-missing-jira-info/","title":"Label Missing Jira Info","text":"Label PRs that don't reference a Jira ticket in the title or description. This uses regex to detect Jira ticket formats in the title (e.g. ABC-1234), and URLs to Jira tickets in the description.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-jira
label.Label Missing Jira Info
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_jira_info:\n# Triggered for PRs that don't have either a Jira ticket number in the title,\n# or a link to a Jira ticket in the PR description.\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: 'F6443B'\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\n
Download this example as a CM file."},{"location":"automations/integrations/jira/link-jira/","title":"Automatically Link PRs to Related Jira Issues","text":"Provide automatic links to Jira issues that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Jira Card
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nprovider: jira\n# Change this to the name of your Jira organization\norgName: org\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_jira:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\njira:\nbaseurl: https://[orgName].atlassian.net/browse/\npattern: r/\\b[A-Za-z]+-\\d+\\b/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"automations/integrations/jira/link-jira/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/jit/label-jit-alerts/","title":"Label Jit Alerts","text":"Label the number of high, medium, and low risk vulnerabilities Jit reports for PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Jit Alerts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in reports %}\nlabel_jit_{{ item.name }}:\nif:\n- {{ item.count > 0}}\nrun:\n- action: add-label@v1\nargs:\nlabel: 'Jit: {{ item.count }} {{ item.name }} vulnerabilities'\ncolor: {{ colors.red if (item.name == 'high') else (colors.orange if (item.name == 'medium' ) else colors.yellow) }}\n{% endfor %}\njit: {{ pr | extractJitFindings }}\nreports:\n- name: high\ncount: {{ jit.metrics.HIGH }}\n- name: medium\ncount: {{ jit.metrics.MEDIUM }}\n- name: low\ncount: {{ jit.metrics.LOW }}\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/jit/review-jit-alerts/","title":"Review Jit Security Alerts","text":"Manage review assignment for high and medium risk Jit security alerts.
Configuration Description
Review Jit High Alerts
Review Jit Medium Alerts
Review Jit Security Alerts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jit_high_alerts:\nif:\n- {{ jit.metrics.HIGH > 0 }}\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [my-organization/security-team]\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR requires additional review because Jit reported one or more high risk vulnerabilities.\nreview_jit_medium_alerts:\nif:\n- {{ jit.metrics.MEDIUM > 0 }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR requires additional reviewers because Jit reported one or more medium risk vulnerabilities.\njit: {{ pr | extractJitFindings }}\n
Download this example as a CM file."},{"location":"automations/integrations/jit/review-jit-ignore-accept/","title":"Review Jit Ignore and Accept","text":"Notify your Security team when someone ignores a Jit vulnerability report and accepts the risk.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Ignore and Accept
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jit_ignore_accept:\nif:\n- {{ pr.conversations | reject(attr='commenter', term='jit-ci') | filter(attr='content', term='#jit_ignore_accept') | some }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [my-organziation/security]\n- action: add-label@v1\nargs:\nlabel: '\u2755 Jit: Ignore - Accept Risk'\n- action: add-comment@v1\nargs:\ncomment: |\nThe security team has been assigned for optional review because this PR ignores a Jit alert and accepts the associated risks.\njit: {{ pr | extractJitFindings }}\n
Download this example as a CM file."},{"location":"automations/integrations/jit/review-jit-secret/","title":"Review Jit Secret Detection","text":"Close PRs where Jit detects a secret and post a comment explaining steps to remedy the situation.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Security Control
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jit_secret:\nif:\n- true\n- {{ jit.vulnerabilities | match(attr='security_control', term='Secret Detection') | some }}\nrun:\n- action: add-comment@v1\nargs: comment: |\nJit detects secrets in this PR. Please complete the following steps:\n1. Undo the commit with git reset and remove all secrets from the files you modified.\n2. Deactivate the secret in any locations its used and replace it with a new key\n3. Commit your changes and resubmit your PR.\n- action: close@v1\njit: {{ pr | extractJitFindings }}\n
Download this example as a CM file."},{"location":"automations/integrations/jsdoc/review-jsdoc/","title":"Review JSDoc Changes","text":"Approve PRs that only contain changes to JSDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\ud83d\udcd3 JSDoc Only label
Review JSDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Assign PRs that only affect JSDocs to the technical writing team and add docs label\nreview_jsdoc:\nif:\n- {{ source.diff.files | match(attr='diff', regex=r/\\/*\\*[\\s\\S]*?\\//) | every }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3JSDoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"automations/integrations/jsdoc/review-jsdoc-input/","title":"Review JSDoc Input Parameters","text":"Warn PR authors when they change JavaScript function or constructor input parameters without updating JSDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JSDoc Input Parameters
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jsdoc_input: if: - {{ source.diff.files | matchDiffLines(regex=r/.*\\s@param/) | nope }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\((?:.*\\:.*\\))/) | some }}\nrun:\n- action: add-comment@v1\nargs: comment: | This PR appears to modify method input parameters, but is missing JSDoc changes. Please check to ensure no JSDoc changes are necessary.\n
Download this example as a CM file."},{"location":"automations/integrations/jsdoc/review-jsdoc-large/","title":"Review JSDoc for Large Changes","text":"Require more extensive reviews for large JavaScript changes that lack JSDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\u26a0\ufe0f Missing JSDoc
LabelReview JSDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Javascript changes that lack JSDoc updates.\nreview_jsdoc_large:\nif:\n- {{ changes.ratio > 25}}\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f No JSDoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to JavaScript classes, but is missing updates to JSDoc. Please double check for any necessary JSDoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n# Sum all the line removed in the PR\ndeletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}\n# Calculate the ratio of new code\nratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/jsdoc/review-jsdoc-new-class/","title":"Enforce JSDoc for New JavaScript Classes","text":"Require JSDoc for all new JavaScript classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing JSDoc
label.Enforce JSDoc for New JavaScript Classes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jsdoc_new_class: if: - {{ is.javascript and is.new }} - {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing JSDoc\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs: comment: | JSDoc is required for all JavaScript classes. Please add JSDoc to all new classes in this PR.\nis:\njavascript: {{ files | extensions | match(list=['js', 'ts']) | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/rdoc/review-rdoc/","title":"Automatically Approve RDoc Changes","text":"Approve PRs that only contain changes to RDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
\ud83d\udcd3 RDoc Only
labelReview RDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_rdoc:\nif:\n- {{ source.diff.files | match(attr='diff', regex=r/^[\\s\\t]*#.*/) | every }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3RDoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [org/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"automations/integrations/rdoc/review-rdoc-input/","title":"Review RDoc Input Parameters","text":"Warn PR authors when they change Ruby function or constructor input parameters without updating RDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review RDoc Input Parameters
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_rdoc_input: if: - {{ source.diff.files | match(attr='diff', regex=r/(\\#.*\\n.*)*def/) | nope }}\n- {{ source.diff.files | match(attr='diff', regex=r/def.*\\(.*\\)/ | some }}\nrun:\n- action: add-comment@v1\nargs: comment: | This PR modifies method input parameters, but is missing RDoc changes. Please check to ensure no RDoc changes are necessary.\n
Download this example as a CM file."},{"location":"automations/integrations/rdoc/review-rdoc-large/","title":"Review RDoc for Large Changes","text":"Require more extensive reviews for large Ruby changes that lack RDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\u26a0\ufe0f Missing RDoc
LabelReview RDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Ruby changes that lack RDoc updates.\nreview_rdoc_large:\nif:\n- {{ changes.additions > 150}}\n- {{ source.diff.files | matchDiffLines(regex=r/(\\#.*\\n.*)*def/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing RDoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to Ruby methods, but is missing updates to RDoc. Please double check for any necessary RDoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/rdoc/review-rdoc-new-class/","title":"Enforce RDoc for New Ruby Classes","text":"Require RDoc for all new Ruby classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing RDoc
label.Enforce RDoc for New Ruby Classes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_rdoc_new_class: if: - {{ is.rb and is.new }} - {{ source.diff.files | match(attr='diff', regex=r/(\\#.*\\n.*)*def/) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing RDoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | RDoc is required for all Ruby classes. Please add documentation for this PR.\nis:\nrb: {{ files | extensions | match(regex=r/rb/) | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/shortcut/label-missing-shortcut/","title":"Label Missing Shortcut","text":"Automatically label PRs that are missing references to Shortcut resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Shortcut Link
labelLabel Missing Shortcut
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_shortcut:\nif:\n- {{not (has.shortcut.ticket_in_title or has.shortcut.ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Shortcut Link\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated Shortcut resource.\nhas:\nshortcut:\nticket_in_title: {{ pr.title | includes(regex=r/(\\w+)\\/sc-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/(app\\.shortcut\\.com)\\/(\\w+)\\/story\\/(\\d+)\\/(\\w+)/) }}\ncolors:\nred: 'b60205'\n
Download this example as a CM file."},{"location":"automations/integrations/shortcut/label-missing-shortcut/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/shortcut/link-shortcut/","title":"Automatically Link PRs to Related Shortcut Tasks","text":"Provide automatic links to Shortcut tasks that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Shortcut Task
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Configure these to match your organization.\nprovider: jira\n# Change this to match the name of your Shortcut organization. This is used in tracker.shortcut.baseurl\norgName: org\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_shortcut:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\nshortcut:\nbaseurl: https://app.shortcut.com/[orgName]/story/\npattern: r/(\\w+)\\/sc-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"automations/integrations/shortcut/link-shortcut/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/integrations/sonar/approve-sonar-clean-code/","title":"Approve Sonar Clean Code","text":"Approve PRs that pass SonarCloud's quality gate.
Configuration Description
Conditions (all must be true):
Automation Actions:
Sonar: Clean Code
label to the PR.Aprove Sonar Clean Code
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_sonar_clean_code:\nif:\n- {{ sonar.bugs.rating == 'A' }}\n- {{ sonar.code_smells.rating == 'A' }}\n- {{ sonar.vulnerabilities.rating == 'A' }}\n- {{ sonar.security_hotspots.rating == 'A' }}\n- {{ sonar.duplications == null or sonar.duplications == 0 }}\nrun: - action: add-label@v1\nargs:\nlabel: '\u2705 Sonar: Clean Code'\ncolor: {{ colors.green }}\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR passes the SonarCloud quality gate check and as been automatically approved.\nsonar: {{ pr | extractSonarFindings }}\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"automations/integrations/sonar/label-sonar/","title":"Label SonarCloud Quality Reports","text":"Label the number of bugs, vulnerabilities, security hotspots, and code smells reported by SonarCloud.
Configuration Description
Conditions (all must be true):
extractSonarFindings
filter functionAutomation Actions:
Label SonarCloud Quality Reports
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in reports %}\nlabel_sonar_{{ item.name }}:\nif:\n- {{ item.count > 0}}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.icon }} sonar:{{ item.name }}-{{ item.rating }}'\ncolor: {{ colors.red if (item.rating == 'E' or item.rating == 'D') else (colors.orange if (item.rating == 'C' ) else colors.yellow) }}\n{% endfor %}\nsonar: {{ pr | extractSonarFindings }}\nreports:\n- name: vulnerabilities\ncount: {{ sonar.vulnerabilities.count }}\nicon: \ud83d\udd13\nrating: {{ sonar.vulnerabilities.rating }}\n- name: code smells\ncount: {{ sonar.code_smells.count }}\nicon: \u2623\ufe0f\nrating: {{ sonar.code_smells.rating }}\n- name: security hotspots\ncount: {{ sonar.security_hotspots.count }}\nicon: \ud83d\udee1\ufe0f\nrating: {{ sonar.security_hotspots.rating }}\n- name: bugs\ncount: {{ sonar.bugs.count }}\nicon: \ud83e\udeb2\nrating: {{ sonar.bugs.rating }}\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/sonar/review-sonar-alerts/","title":"Review Sonar Security Alerts","text":"Require additional reviews for Sonar security alerts. gitStream will remove this requirement if the alerts are resolved.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/security-team
team. Customize this to match your organization.Review Sonar Alerts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_sonar_alerts:\nif:\n- {{ sonar.code_smells.rating != 'A' or sonar.vulnerabilities.rating != 'A' or sonar.security_hotspots.rating != 'A'}}\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [my-organization/security-team]\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR requires additional review because it fails to meet SonarCloud clean code standards.\nsonar: {{ pr | extractSonarFindings }}\n
Download this example as a CM file."},{"location":"automations/integrations/sonar/review-sonar-duplications/","title":"Review Sonar Duplications","text":"Request changes when Sonar reports an excessive level of duplicated code.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Sonar Duplications
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_sonar_duplications:\nif:\n- {{ sonar.duplications > 3 }}\nrun: - action: add-label@v1\nargs:\nlabel: 'Sonar: {{ sonar.duplications}}% duplication'\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: |\nSonar reports an excessive level of code duplication. Please consider refactoring your PR to reduce duplications.\nsonar: {{ pr | extractSonarFindings }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/integrations/swimm/approve-swimm/","title":"Approve Swimm Changes","text":"Approve changes that only affect Swimm documentation.
Configuration Description
Conditions (all must be true):
.swm
extension.Automation Actions:
swimm-docs-only
labelApprove Swimm Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_swimm_changes:\n# Triggered for any changes to Swimm documentation\nif:\n- {{ branch.diff.files_metadata | match(attr='file', regex=r/\\.swm\\//) | every }}\n# Apply a swimm-docs-only label, approve the PR and explain why in a comment.\nrun: - action: add-label@v1\nargs:\nlabel: 'swimm-docs-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is considered a safe change as it only affects Swimm Docs. \nIt has been automatically approved.\n
Download this example as a CM file. Special thanks to Omerr for providing this example.
"},{"location":"automations/integrations/terraform/review-new-module/","title":"Review New Terraform Modules","text":"Request changes if a PR that creates a new Terraform module which do not conform to the required directory structure.
Configuration Description
Conditions (all must be true):
/modules
directory.Automation Actions:
\u26a0\ufe0f Missing Terraform Components
Review New Module
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n{% set misslist = [] %}\n{% for pattern in terraform %}\n{% if (newfilesinpr | match(term=pattern) | nope) %}\n{% set misslist = misslist + [pattern+' '] %}\n{% endif %}\n{% endfor %} automations:\nreview_new_terraform_module:\nif: - {{misslist | match(regex=r/.*/) | some}}\n- {{is.mainfile and is.mainfilenotinroot }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nNew terraform modules must contain all required components before merging. Please update your PR with the required components and gitStream will automatically remove this comment once completed.\nHere are the required components, {{misslist}} should be customized appropriately:\nmy_module/\n\u251c\u2500\u2500 main.tf\n\u251c\u2500\u2500 outputs.tf\n\u251c\u2500\u2500 providers.tf\n- action: add-label@v1\nargs:\nlabel: '\u26a0\ufe0f Missing Terraform Components'\ncolor: '#FFA500'\nresources:\nmodule_directory: 'modules'\nterraform:\n- main.tf\n- outputs.tf\n- providers.tf\nis:\nmainfile: {{newfilesinpr | match(term = \"main.tf\") | some}}\nmainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = \"main.tf\") | nope }}\nnewfilesinpr:\n{{ branch.diff.files_metadata | map(attr='new_file')}}\n
Download this example as a CM file."},{"location":"automations/integrations/terraform/review-terraform/","title":"Require Reviewers for Terraform changes","text":"Automatically assign org/infrastructure
team for reviewing changes when PR contains Terraform file changes.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_terraform:\n# Triggered for any changes to Terraform files\nif:\n- {{ files | match(regex=r/.*\\.tf.*/) | some }}\n# Assign infrastructure team as reviewer for change in Terraform files\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [org/infrastructure]\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR affects Terraform configurations and requires a review from the Infra team.\n
Download this example as a CM file."},{"location":"automations/integrations/terraform/review-terraform-module-name/","title":"Review Terraform Module Name","text":"Request changes if a PR creates a new Terraform module that is missing a required prefix or keyword in the name.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Module Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Prefix Check Logic\n{% set prefixcheck = [] %}\n{% for pattern in terraform.prefixes %}\n{% if(newfilesinpr | match(term=module_location + pattern) | some) %}\n{% set prefixcheck = prefixcheck + [true]%}\n{% else %}\n{% set prefixcheck = prefixcheck + [false] %}\n{% endif %}\n{% endfor %}\nautomations:\nreview_new_terraform_module:\nif: - {{is.mainfile and is.mainfilenotinroot}}\n- {{module_name_checks.prefix or module_name_checks.keyword}}\nrun:\n- action: request-changes@v1\nargs:\ncomment: |\nTerraform module names must contain a required prefix and keyword:\n* Prefixes: {{ terraform.prefixes }}\n* Keywords: {{ terraform.keywords }}\nmodule_name_checks:\nprefix: {{prefixcheck | match(term='true') | nope}}\nkeyword: {{newfilesinpr | match(list=terraform.keywords) | nope}}\nmodule_location: infrastructure/modules/\nterraform:\nprefixes: ['aws', 'gcp', 'azure']\nkeywords: ['db', 'networking', 'security']\nis:\nmainfile: {{newfilesinpr | match(term = \"main.tf\") | some}}\nmainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = \"main.tf\") | nope }}\nnewfilesinpr:\n{{ branch.diff.files_metadata | map(attr='new_file')}}\n
Download this example as a CM file."},{"location":"automations/integrations/terraform/review-terraform-source-version/","title":"Review Terraform Source Version","text":"Ensure that all Terraform modules imported via a source URL specify a version.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_terraform_source_version:\n# Check if New Content contains a source URL, the URL is not part of allow list and lacks version reference\nif: - {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\\\".*(http|https).*\\\"/) | some }}\n- {{ source.diff.files | match(attr='new_content', list=allowlist) | nope }}\n- {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\\?ref=v.*/) | nope }}\nrun:\n- action: request-changes@v1\nargs:\ncomment: |\nYou must reference a specific version when accessing Terraform module sources via URL, e.g. `?ref=v1.0.0`. Please update your Terraform files to follow this practice.\nallowlist:\n- 'https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git'\n- 'https://github.com/terraform-aws-modules/terraform-aws-vpc.git'\n- 'https://github.com/terraform-aws-modules/terraform-aws-eks.git'\n
Download this example as a CM file."},{"location":"automations/label-deleted-files/","title":"Label Deleted Files","text":"Label PRs that delete files.
Configuration Description
Conditions (all must be true):
Automation Actions:
deleted-files
label to the PR.Label Deleted Files
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Apply a label that indicates when a PR deletes files\n# This uses the `has` custom expression found at the bottom of this file\nlabel_deleted_files:\nif:\n- {{ has.deleted_files }}\nrun: - action: add-label@v1\nargs:\nlabel: 'deleted-files'\ncolor: '#DF9C04'\n# This is used in the `label_deleted_files` automation\nhas:\ndeleted_files: {{ source.diff.files | map(attr='new_file') | match(term='/dev/null') | some }}\n
Download this example as a CM file."},{"location":"automations/label-deleted-files/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/label-missing-jira-info/","title":"Index","text":"This file has moved: /docs/automations/integrations/jira/label-missing-jira-info
"},{"location":"automations/label-missing-project-tracker/","title":"Flag Missing Project Tracking Info","text":"Label PRs that lack a reference to a project tracker issue (Jira, Azure Boards, Shortcut and Asana) in the PR title or description.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Project Tracker
Label Missing Project Tracker
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_project_tracker:\nif:\n- {{not (has[provider].ticket_in_title or has[provider].ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Project Tracker\"\ncolor: 'F6443B'\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated resource in your team's project tracker.\nhas:\njira:\nticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\nasana:\nticket_in_title: {{ pr.title | includes(regex=r/asana-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/app\\.asana.\\com\\/(\\d+)\\/(\\d+)\\/(\\d+)\\/(\\d+)\\/(\\d+)/) }}\nazure:\nticket_in_title: {{ pr.title | includes(regex=r/(\\w+)-(\\w+)-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/(dev\\.azure\\.com|(\\w+)\\.visualstudio\\.com)\\/(\\w+)\\/(\\w+)\\/_workitems\\/edit\\/(\\d+)/) }}\nshortcut:\nticket_in_title: {{ pr.title | includes(regex=r/(\\w+)\\/sc-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/(app\\.shortcut\\.com)\\/(\\w+)\\/story\\/(\\d+)\\/(\\w+)/) }}\nprovider: jira\n
Download this example as a CM file."},{"location":"automations/label-prs-without-tests/","title":"Label PRs Without Tests","text":"Apply a missing-tests
label to any PRs that don't update tests. gitStream will remove this label if the contributor adds a test change to the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-tests
label.Label PRs Without Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_prs_without_tests:\nif:\n- {{ files | match(regex=r/[^a-zA-Z0-9](spec|test|tests)[^a-zA-Z0-9]/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: 'missing-tests'\ncolor: '#E94637'\n
Download this example as a CM file."},{"location":"automations/label-prs-without-tests/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/languages/golang/","title":"Integrate gitStream with Golang","text":""},{"location":"automations/languages/golang/#approve-golang-log-output-changes","title":"Approve Golang Log Output Changes","text":"Approve changes to Golang files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
.go
log
object.Automation Actions:
log-output-only
labelApprove Golang Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_golang_log_output:\n# Triggered for Golang changes that only affect the console.log() method\nif: - {{ files | extensions | match(term='go') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*log\\.Println/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/golang/#review-missing-golang-tests","title":"Review Missing Golang Tests","text":"Automatically request changes for Golang PRs that are missing tests.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Golang Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\\/(?!.*\\_test\\.go$).*\\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/.*\\_test\\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\\/(?!.*\\_test\\.go$).*\\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/.*\\_test\\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_golang_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Golang files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/golang/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"automations/languages/golang/approve-golang-log-output/","title":"Approve Golang Log Output Changes","text":"Approve changes to Golang files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
.go
log
object.Automation Actions:
log-output-only
labelApprove Golang Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_golang_log_output:\n# Triggered for Golang changes that only affect the console.log() method\nif: - {{ files | extensions | match(term='go') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*log\\.Println/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/golang/review-missing-golang-tests/","title":"Review Missing Golang Tests","text":"Automatically request changes for Golang PRs that are missing tests.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Golang Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\\/(?!.*\\_test\\.go$).*\\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/.*\\_test\\.go$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^(pkg|internal)\\/(?!.*\\_test\\.go$).*\\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/.*\\_test\\.go$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_golang_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Golang files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/html/","title":"Integrate gitStream with HTML and CSS","text":""},{"location":"automations/languages/html/#request-changes-for-css-important-tags","title":"Request Changes for CSS Important Tags","text":"Flag the use of !important
in CSS files and automatically request changes.
Configuration Description
Conditions (all must be true):
!important
Automation Actions:
\u26a0\ufe0f Includes !important tag
Review Important Tags in CSS Files
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_javascript_formatting:\nif:\n- {{ files | extensions | match(term='css') | some }}\n- {{ source.diff.files | matchDiffLines(regex=r/!important/) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '\u26a0\ufe0f Includes !important tag'\ncolor: '{{ colors.orange }}'\n- action: request-changes@v1\nargs:\ncomment: |\nPlease remove the `!important` tag from your CSS.\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/html/#flag-missing-html-tags","title":"Flag Missing HTML Tags","text":"Request changes for HTML files that lack the canonical and robots tag.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Required Tag
label.Flag Missing HTML Tags
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nflag_missing_html_tags:\nif:\n- {{ is.html and is.new }}\n- {{ source.diff.files | matchDiffLines(regex=r/rel=\"canonical\"/) | nope }}\n- {{ source.diff.files | matchDiffLines(regex=r/meta name=\"robots\"/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Required Tag\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: | Please ensure new HTML files contain canonical and robots meta tags.\nis:\nhtml: {{ files | extensions | match(term='html') | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/languages/html/#flag-duplicate-h1","title":"Flag Duplicate H1","text":"Automatically request changes when PRs contain HTML files that have more than one H1 heading.
Configuration Description
Conditions (all must be true):
Automation Actions:
Flag Duplicate H1
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nflag_duplicate_h1:\nif:\n- {{ duplicateH1 > 0 }}\nrun: - action: request-changes@v1\nargs:\ncomment: | This PR contains HTML files with multiple H1 tags. Please ensure that each HTML file has only one H1 tag.\nduplicateH1: {{ source.diff.files | filter(attr='new_content', regex=r/<h1>(.|\\n)*<h1>/) | length }}\n
Download this example as a CM file."},{"location":"automations/languages/html/#enforce-html-title-length-requirements","title":"Enforce HTML Title Length Requirements","text":"Automatically request changes for <title>
tags that don't comply with best practices.
Configuration Description
Conditions (all must be true):
<title>
tag that is less than 30 or greater than 90 characters.Automation Actions:
Enforce HTML Title Length Requirements
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_html_title_length:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/(<title>([\\w\\W]{1,29})<\\/title>)|(<title>([\\w\\W]{61,})<\\/title>)/) | some }}\nrun: - action: request-changes@v1\nargs:\ncomment: | Please ensure that all HTML titles are between 30 and 60 characters.\n
Download this example as a CM file."},{"location":"automations/languages/html/#enforce-image-alt-attributes","title":"Enforce Image Alt Attributes","text":"Automatically request changes for PRs HTML files that are missing image alt attributes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing alt label
labelEnforce Image Alt Attributes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_image_alt:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/<img src/) | some }}\n- {{ source.diff.files | matchDiffLines(regex=r/<img src.*alt=/) | nope}}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing alt label\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: | Please ensure that all images in HTML files have an alt attribute. For example: <img alt=\"Alt Message\">\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/languages/html/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"automations/languages/html/enforce-html-title-length/","title":"Enforce HTML Title Length Requirements","text":"Automatically request changes for <title>
tags that don't comply with best practices.
Configuration Description
Conditions (all must be true):
<title>
tag that is less than 30 or greater than 90 characters.Automation Actions:
Enforce HTML Title Length Requirements
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_html_title_length:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/(<title>([\\w\\W]{1,29})<\\/title>)|(<title>([\\w\\W]{61,})<\\/title>)/) | some }}\nrun: - action: request-changes@v1\nargs:\ncomment: | Please ensure that all HTML titles are between 30 and 60 characters.\n
Download this example as a CM file."},{"location":"automations/languages/html/enforce-image-alt/","title":"Enforce Image Alt Attributes","text":"Automatically request changes for PRs HTML files that are missing image alt attributes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing alt label
labelEnforce Image Alt Attributes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_image_alt:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/<img src/) | some }}\n- {{ source.diff.files | matchDiffLines(regex=r/<img src.*alt=/) | nope}}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing alt label\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: | Please ensure that all images in HTML files have an alt attribute. For example: <img alt=\"Alt Message\">\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/languages/html/flag-duplicate-h1/","title":"Flag Duplicate H1","text":"Automatically request changes when PRs contain HTML files that have more than one H1 heading.
Configuration Description
Conditions (all must be true):
Automation Actions:
Flag Duplicate H1
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nflag_duplicate_h1:\nif:\n- {{ duplicateH1 > 0 }}\nrun: - action: request-changes@v1\nargs:\ncomment: | This PR contains HTML files with multiple H1 tags. Please ensure that each HTML file has only one H1 tag.\nduplicateH1: {{ source.diff.files | filter(attr='new_content', regex=r/<h1>(.|\\n)*<h1>/) | length }}\n
Download this example as a CM file."},{"location":"automations/languages/html/flag-missing-html-tags/","title":"Flag Missing HTML Tags","text":"Request changes for HTML files that lack the canonical and robots tag.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Required Tag
label.Flag Missing HTML Tags
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nflag_missing_html_tags:\nif:\n- {{ is.html and is.new }}\n- {{ source.diff.files | matchDiffLines(regex=r/rel=\"canonical\"/) | nope }}\n- {{ source.diff.files | matchDiffLines(regex=r/meta name=\"robots\"/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Required Tag\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: | Please ensure new HTML files contain canonical and robots meta tags.\nis:\nhtml: {{ files | extensions | match(term='html') | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/languages/html/review-css-important/","title":"Review Important Tags in CSS Files","text":"Flag the use of !important
in CSS files and automatically request changes.
Configuration Description
Conditions (all must be true):
!important
Automation Actions:
\u26a0\ufe0f Includes !important tag
Review Important Tags in CSS Files
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_javascript_formatting:\nif:\n- {{ files | extensions | match(term='css') | some }}\n- {{ source.diff.files | matchDiffLines(regex=r/!important/) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '\u26a0\ufe0f Includes !important tag'\ncolor: '{{ colors.orange }}'\n- action: request-changes@v1\nargs:\ncomment: |\nPlease remove the `!important` tag from your CSS.\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/java/","title":"Integrate gitStream with Java","text":""},{"location":"automations/languages/java/#approve-java-log-output-changes","title":"Approve Java Log Output Changes","text":"Approve changes to Java files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Java Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_java_log_output:\n# Triggered for Java changes that only affect the logger method\nif: - {{ files | extensions | match(term='java') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*logger\\.(trace|fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/java/#review-missing-java-tests","title":"Review Missing Java Tests","text":"Automatically request changes for Java PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Java Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*Test\\.java$).*\\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*Test\\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*Test\\.java$).*\\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*Test\\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_java_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Java files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/java/#review-java-test-names","title":"Review Java Test Names","text":"Automatically request changes for Java test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Java Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0 newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/test\\/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/test\\/) | length }}\nautomations:\nreview_java_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/test\\/) | match(attr='new_file', regex=r/Test.java$/) | nope }}\nrun: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the Java test name conventions. A test file name needs to have the word Test at the end of class name. For example, if you are testing a class called Data then the test file name has to be DataTest.java.\n
Download this example as a CM file."},{"location":"automations/languages/java/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"automations/languages/java/approve-java-log-output/","title":"Approve Java Log Output Changes","text":"Approve changes to Java files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Java Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_java_log_output:\n# Triggered for Java changes that only affect the logger method\nif: - {{ files | extensions | match(term='java') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*logger\\.(trace|fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/java/review-java-test-name/","title":"Review Java Test Name","text":"Automatically request changes for Java test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Java Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0 newTests: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/test\\/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/test\\/) | length }}\nautomations:\nreview_java_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/test\\/) | match(attr='new_file', regex=r/Test.java$/) | nope }}\nrun: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the Java test name conventions. A test file name needs to have the word Test at the end of class name. For example, if you are testing a class called Data then the test file name has to be DataTest.java.\n
Download this example as a CM file."},{"location":"automations/languages/java/review-missing-java-tests/","title":"Review Missing Java Tests","text":"Automatically request changes for Java PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Java Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*Test\\.java$).*\\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*Test\\.java$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*Test\\.java$).*\\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*Test\\.java$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_java_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Java files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/javascript/","title":"Integrate gitStream with JavaScript","text":""},{"location":"automations/languages/javascript/#auto-approve-javascript-log-output-changes","title":"Auto-Approve JavaScript Log Output Changes","text":"Approve changes to JavaScript files that only affect lines of code that invoke the console.log() method.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove JavaScript Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_javascript_log_output:\n# Triggered for JavaScript changes that only affect the console.log() method\nif: - {{ files | match(regex=r/\\.js$|\\.ts$/) | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^[+-].*console\\.log/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file. "},{"location":"automations/languages/javascript/#auto-approve-javascript-formatting-change","title":"Auto-Approve JavaScript Formatting Change","text":"Approve PRs that only contain formatting changes to JavaScript or TypeScript files.
Configuration Description
Conditions (all must be true):
.js
or .ts
Automation Actions:
code-formatting
label.Approve JavaScript Formatting Change
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_javascript_formatting:\nif:\n- {{ files | extensions | match(list=['js', 'ts']) | every }}\n- {{ source.diff.files | isFormattingChange }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: code-formatting\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR only contains formatting changes and has been approved.\n
Download this example as a CM file. "},{"location":"automations/languages/javascript/#review-missing-javascript-tests","title":"Review Missing JavaScript Tests","text":"Request changes for JavaScript PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-tests
labelReview Missing JavaScript Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*\\.test\\.js$).*\\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*\\.test\\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*\\.test\\.js$).*\\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*\\.test\\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_javascript_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new JavaScript files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/javascript/#review-javascript-test-name","title":"Review JavaScript Test Name","text":"Automatically request changes for JavaScript test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JavaScript Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | length }}\nautomations:\nreview_javascript_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | match(attr='new_file', regex=r/.test.js$/) | nope }}\nrun: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the JavaScript test name conventions. A test file name needs to have the suffix .test after class name. For example, if you are testing a class file called Data.js then the test file name has to be data.test.js.\n
Download this example as a CM file."},{"location":"automations/languages/javascript/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/languages/javascript/approve-javascript-formatting-change/","title":"Approve JavaScript Formatting Changes","text":"Approve PRs that only contain formatting changes to JavaScript or TypeScript files.
Configuration Description
Conditions (all must be true):
.js
or .ts
Automation Actions:
code-formatting
label.Approve JavaScript Formatting Change
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_javascript_formatting:\nif:\n- {{ files | extensions | match(list=['js', 'ts']) | every }}\n- {{ source.diff.files | isFormattingChange }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: code-formatting\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR only contains formatting changes and has been approved.\n
Download this example as a CM file. "},{"location":"automations/languages/javascript/approve-javascript-log-output/","title":"Approve JavaScript Log Output Changes","text":"Approve changes to JavaScript files that only affect lines of code that invoke the console.log() method.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove JavaScript Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_javascript_log_output:\n# Triggered for JavaScript changes that only affect the console.log() method\nif: - {{ files | match(regex=r/\\.js$|\\.ts$/) | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^[+-].*console\\.log/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file. "},{"location":"automations/languages/javascript/review-javascript-test-name/","title":"Review JavaScript Test Name","text":"Automatically request changes for JavaScript test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JavaScript Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | length }}\nautomations:\nreview_javascript_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^test/) | match(attr='new_file', regex=r/.test.js$/) | nope }}\nrun: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the JavaScript test name conventions. A test file name needs to have the suffix .test after class name. For example, if you are testing a class file called Data.js then the test file name has to be data.test.js.\n
Download this example as a CM file."},{"location":"automations/languages/javascript/review-missing-javascript-tests/","title":"Review Missing JavaScript Tests","text":"Request changes for JavaScript PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-tests
labelReview Missing JavaScript Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*\\.test\\.js$).*\\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*\\.test\\.js$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!.*\\.test\\.js$).*\\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/src\\/.*\\.test\\.js$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_javascript_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new JavaScript files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/python/","title":"Integrate gitStream with Python","text":""},{"location":"automations/languages/python/#auto-approve-python-log-output-changes","title":"Auto-Approve Python Log Output Changes","text":"Approve changes to Python files that only affect lines of code that invoke a specified logging object.
Configuration Description
Conditions (all must be true):
logger
object. This should be customized to your environment.Automation Actions:
log-output-only
labelApprove Python Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_python_log_output:\n# Triggered for python changes that only affect lines of code that invoke a logger object. \n# Modify 'logger' to match your dev environment.\nif: - {{ files | match(regex=r/\\.py$/) | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^[+-].*logger\\.(trace|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file. "},{"location":"automations/languages/python/#auto-approve-python-formatting-changes","title":"Auto-Approve Python Formatting Changes","text":"Approve PRs that only contain formatting changes to Python files.
Configuration Description
Conditions (all must be true):
.py
.Automation Actions:
code-formatting
label.Approve Python Formatting Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_python_formatting:\nif:\n- {{ files | extensions | match(list=['py']) | every }}\n- {{ source.diff.files | isFormattingChange }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: code-formatting\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR only contains formatting changes and has been approved.\n
Download this example as a CM file. "},{"location":"automations/languages/python/#review-missing-python-tests","title":"Review Missing Python Tests","text":"Automatically request changes for Python PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Python Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!test_.*\\.py$).*\\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\\/test_.*\\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!test_.*\\.py$).*\\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\\/test_.*\\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_python_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Python files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/python/#review-python-test-name","title":"Review Python Test Name","text":"Automatically request changes for Python test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Python Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | length }}\nautomations:\nreview_python_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | match(attr='new_file', regex=r/test_.*\\.py$/) | nope }} run: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the Python test name conventions. A test file name needs to have the prefix test_ before class name. For example, if you are testing a class file called Data.py then the test file name has to be test_data.py.\n
Download this example as a CM file."},{"location":"automations/languages/python/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/languages/python/approve-python-formatting-change/","title":"Approve Python Formatting Changes","text":"Approve PRs that only contain formatting changes to Python files.
Configuration Description
Conditions (all must be true):
.py
.Automation Actions:
code-formatting
label.Approve Python Formatting Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_python_formatting:\nif:\n- {{ files | extensions | match(list=['py']) | every }}\n- {{ source.diff.files | isFormattingChange }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: code-formatting\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR only contains formatting changes and has been approved.\n
Download this example as a CM file. "},{"location":"automations/languages/python/approve-python-log-output/","title":"Approve Python Log Output Changes","text":"Approve changes to Python files that only affect lines of code that invoke a specified logging object.
Configuration Description
Conditions (all must be true):
logger
object. This should be customized to your environment.Automation Actions:
log-output-only
labelApprove Python Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_python_log_output:\n# Triggered for python changes that only affect lines of code that invoke a logger object. \n# Modify 'logger' to match your dev environment.\nif: - {{ files | match(regex=r/\\.py$/) | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^[+-].*logger\\.(trace|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file. "},{"location":"automations/languages/python/review-missing-python-tests/","title":"Review Missing Python Tests","text":"Automatically request changes for Python PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Python Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!test_.*\\.py$).*\\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\\/test_.*\\.py$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^src\\/(?!test_.*\\.py$).*\\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests\\/test_.*\\.py$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_python_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Python files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/python/review-python-test-name/","title":"Review Python Test Name","text":"Automatically request changes for Python test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Python Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | length }}\nautomations:\nreview_python_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^tests/) | match(attr='new_file', regex=r/test_.*\\.py$/) | nope }} run: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the Python test name conventions. A test file name needs to have the prefix test_ before class name. For example, if you are testing a class file called Data.py then the test file name has to be test_data.py.\n
Download this example as a CM file."},{"location":"automations/languages/ruby/","title":"Integrate gitStream with Ruby","text":""},{"location":"automations/languages/ruby/#approve-ruby-log-output-changes","title":"Approve Ruby Log Output Changes","text":"Approve changes to Ruby files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Ruby Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_ruby_log_output:\n# Triggered for Ruby changes that only affect the logger method\nif: - {{ files | extensions | match(term='rb') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*logger\\.(fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/ruby/#review-missing-ruby-tests","title":"Review Missing Ruby Tests","text":"Automatically request changes for Ruby PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Ruby Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^app\\/(?!.*\\_spec\\.rb$).*\\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/spec\\/.*\\_spec\\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^app\\/(?!.*\\_spec\\.rb$).*\\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/spec\\/.*\\_spec\\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_ruby_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Ruby files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/ruby/#review-ruby-test-name","title":"Review Ruby Test Name","text":"Automatically request changes for Ruby test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Ruby Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | length }}\nautomations:\nreview_ruby_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | match(attr='new_file', regex=r/_spec.rb$/) | nope }}\nrun: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the Ruby test name conventions. A test file name needs to have the suffix _spec after class name. For example, if you are testing a class file called data.rb then the test file name has to be data_spec.rb.\n
Download this example as a CM file."},{"location":"automations/languages/ruby/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"automations/languages/ruby/approve-ruby-log-output/","title":"Approve Ruby Log Output Changes","text":"Approve changes to Ruby files that only affect lines of code that invoke the logger object.
Configuration Description
Conditions (all must be true):
Automation Actions:
log-output-only
labelApprove Ruby Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_ruby_log_output:\n# Triggered for Ruby changes that only affect the logger method\nif: - {{ files | extensions | match(term='rb') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*logger\\.(fatal|debug|info|warn|error)/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/ruby/review-missing-ruby-tests/","title":"Review Missing Ruby Tests","text":"Automatically request changes for Ruby PRs that lack test files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Missing Ruby Tests
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewFiles: {{ source.diff.files | filter(attr='new_file', regex=r/^app\\/(?!.*\\_spec\\.rb$).*\\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/spec\\/.*\\_spec\\.rb$/) | filter(attr='original_file', regex=r/^$/) | map(attr='new_file') }}\nnewFilesCount: {{ source.diff.files | filter(attr='new_file', regex=r/^app\\/(?!.*\\_spec\\.rb$).*\\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/spec\\/.*\\_spec\\.rb$/) | filter(attr='original_file', regex=r/^$/) | length }}\nautomations:\nreview_missing_ruby_tests:\nif:\n- {{ newFilesCount != newTestsCount }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Tests\"\ncolor: {{ colors.orange }} - action: request-changes@v1\nargs:\ncomment: |\nSome of your new Ruby files are missing corresponding tests. Please ensure that all new files have a corresponding test file.\n**New Files**: {{ newFilesCount }}\n{{ newFiles }}\n**New Tests**: {{ newTestsCount }}\n{{ newTests }}\ncolors:\norange: 'd93f0b'\n
Download this example as a CM file."},{"location":"automations/languages/ruby/review-ruby-test-name/","title":"Review Ruby Test Name","text":"Automatically request changes for Ruby test files that fail to match the required naming convention.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Ruby Test Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nnewTests: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) }}\nnewTestsCount: {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | length }}\nautomations:\nreview_ruby_test_name:\nif:\n- {{ newTestsCount > 0}} - {{ source.diff.files | filter(attr='new_file', regex=r/^spec/) | match(attr='new_file', regex=r/_spec.rb$/) | nope }}\nrun: - action: request-changes@v1\nargs:\ncomment: |\nThe test file name does not follow the Ruby test name conventions. A test file name needs to have the suffix _spec after class name. For example, if you are testing a class file called data.rb then the test file name has to be data_spec.rb.\n
Download this example as a CM file."},{"location":"automations/languages/rust/","title":"Integrate gitStream with Rust","text":""},{"location":"automations/languages/rust/#approve-rust-log-output-changes","title":"Approve Rust Log Output Changes","text":"Approve changes to Rust files that only affect lines of code that invoke the logging marcos.
Configuration Description
Conditions (all must be true):
.rs
print
, println
or dbg
macros or use the log
crate macros.Automation Actions:
log-output-only
labelApprove Rust Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_rust_log_output:\n# Triggered for Rust changes that only affect the logging macros\nif: - {{ files | extensions | match(term='rs') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*\\b(println|print|dbg|error|warn|info|debug|trace)\\b!/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/languages/rust/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/languages/rust/approve-rust-log-output/","title":"Approve Rust Log Output Changes","text":"Approve changes to Rust files that only affect lines of code that invoke the logging marcos.
Configuration Description
Conditions (all must be true):
.rs
print
, println
or dbg
macros or use the log
crate macros.Automation Actions:
log-output-only
labelApprove Rust Log Output Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_rust_log_output:\n# Triggered for Rust changes that only affect the logging macros\nif: - {{ files | extensions | match(term='rs') | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/^.*\\b(println|print|dbg|error|warn|info|debug|trace)\\b!/, ignoreWhiteSpaces=true) | every }}\nrun: - action: add-label@v1\nargs:\nlabel: 'log-output-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR has been approved because it only contains changes to log output\n
Download this example as a CM file."},{"location":"automations/percent-new-code/","title":"Calculate the Percentage of New Code","text":"Post a comment that indicates what percentage of the PR contains new code.
Configuration Description
Conditions (all must be true):
Automation Actions:
changes
custom expression to post a comment that indicates what percentage of the PR is new code. Calculate the Percentage of New Code
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\npercent_new_code:\nif:\n- true\nrun: - action: add-comment@v1\nargs:\ncomment: |\nThis PR is {{ changes.ratio }}% new code.\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n# Sum all the line removed in the PR\ndeletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}\n# Calculate the ratio of new code\nratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}\n
Download this example as a CM file."},{"location":"automations/percent-new-code/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/provide-estimated-time-to-review/","title":"Provide Estimated Time to Review","text":"Label all PRs with an estimated number of minutes it would take someone to review. gitStream will automatically update this label whenever a PR changes.
Configuration Description
Conditions (all must be true):
Automation Actions:
Provide Estimated Time to Review
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nestimated_time_to_review:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"{{ calc.etr }} min review\"\ncolor: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}\ncalc:\netr: {{ branch | estimatedReviewTime }}\ncolors:\nred: 'b60205'\nyellow: 'fbca04'\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"automations/provide-estimated-time-to-review/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/request-screenshot/","title":"Request Screenshot","text":"If the PR lacks an image file, or link to an image in the description, apply a no-screenshot
label and post a comment to request a screenshot. If the PR author updates the description, gitStream will remove the label.
Configuration Description
Conditions (all must be true):
Automation Actions:
no-screenshot
label.Request Screenshot
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations: request_screenshot:\n# Triggered for PRs that lack an image file or link to an image in the PR description\nif:\n- {{ not (has.screenshot_link or has.image_uploaded) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: 'no-screenshot'\ncolor: '#FF000A'\n- action: add-comment@v1\nargs:\ncomment: |\nBe a life saver \ud83d\udedf by adding a screenshot of the changes you made.\nhas:\nscreenshot_link: {{ pr.description | includes(regex=r/!\\[.*\\]\\(.*(jpg|svg|png|gif|psd).*\\)/) }}\nimage_uploaded: {{ pr.description | includes(regex=r/<img.*src.*(jpg|svg|png|gif|psd).*>/) }}\n
Download this example as a CM file."},{"location":"automations/request-screenshot/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/branch-management/","title":"Manage git Branches With gitStream","text":"Use gitStream to enforce branch naming conventions, review assignment, and other branch managment workflows.
Enforce Branch Naming Conventions - Automatically enforce prefixes or keywords in PR branch names.
Assign Reviewers Based on Target Branch - Automatically assign PR reviewers for target branches that include a specified keyword.
"},{"location":"automations/standard/branch-management/#enforce-branch-naming-conventions","title":"Enforce Branch Naming Conventions","text":"Automatically enforce prefixes or keywords in PR branch names.
Configuration Description
Conditions (all must be true):
feature
fix
or stable
abc-
followed by a number.ignoreList
custom expression.Automation Actions:
\u2757 Incorrect Branch Name
Enforce Branch Naming Conventions
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_branch_name: if: - {{ not has.requiredBranchPrefix }}\n- {{ not has.requiredBranchKeyword }}\n- {{ not ignoreList }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u2757 Incorrect Branch Name\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: |\nAll PR branch names must be prefixed by feature, stable, or fix, and must contain a reference to a Jira ticket. E.g. 'feature-abc-1234'\nPlease move your changes to a new branch that meets these requirements and open a new PR.\n- action: close@v1\nhas:\nrequiredBranchPrefix: {{ branch.name | includes(regex=r/^(feature|stable|fix)/) }}\nrequiredBranchKeyword: {{ branch.name | includes(regex=r/abc+-\\d+/) }}\nignoreList: {{ branch.name | match(regex=r/^(development|staging)/) }}\n
Download this example as a CM file. "},{"location":"automations/standard/branch-management/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/branch-management/enforce-branch-name/","title":"Enforce Branch Naming Conventions","text":"Automatically enforce prefixes or keywords in PR branch names.
Configuration Description
Conditions (all must be true):
feature
fix
or stable
abc-
followed by a number.ignoreList
custom expression.Automation Actions:
\u2757 Incorrect Branch Name
Enforce Branch Naming Conventions
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_branch_name: if: - {{ not has.requiredBranchPrefix }}\n- {{ not has.requiredBranchKeyword }}\n- {{ not ignoreList }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u2757 Incorrect Branch Name\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: |\nAll PR branch names must be prefixed by feature, stable, or fix, and must contain a reference to a Jira ticket. E.g. 'feature-abc-1234'\nPlease move your changes to a new branch that meets these requirements and open a new PR.\n- action: close@v1\nhas:\nrequiredBranchPrefix: {{ branch.name | includes(regex=r/^(feature|stable|fix)/) }}\nrequiredBranchKeyword: {{ branch.name | includes(regex=r/abc+-\\d+/) }}\nignoreList: {{ branch.name | match(regex=r/^(development|staging)/) }}\n
Download this example as a CM file. "},{"location":"automations/standard/enforce-copyright-header/","title":"Enforce Copyright Headers","text":"Automatically require copyright headers for all new source code files.
Configuration Description
Conditions (all must be true):
Automation Actions:
Enforce Copyright Headers
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_copyright_header: if: - {{ source.diff.files | filter(attr='new_file', regex=r/src\\//) | map(attr='original_file') | match(regex=r/^$/) | some }}\n- {{ source.diff.files | matchDiffLines(regex=licence.licenceRegex) | nope }}\nrun:\n- action: add-comment@v1\nargs: comment: | All new files in the '/src' directory must include the required copyright header at the top of the file. For example:\n// Copyright (c) ORG and contributors. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for details.\nlicence:\nlicenceRegex: r/(Copyright \\(c\\) )|(Licensed under the MIT license)/\n
Download this example as a CM file. "},{"location":"automations/standard/enforce-copyright-header/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/enforce-pr-title/","title":"Enforce PR Semantic Title Names","text":"Automatically enforce PR naming conventions; this example expects the format: <type>(<scope>): <short summary>
Configuration Description
Conditions (all must be true):
Automation Actions:
Enforce PR Semantic Title Names
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nenforce_pr_title: if: - {{ pr.title | match(regex=titlePolicy.titleRegex) | nope }}\nrun:\n- action: request-changes@v1\nargs: comment: | All PRs must be titled according to our semantic naming policy: `<type>(<scope>): <short summary>`\nType must be one of the following:\n* build\n* ci \n* docs\n* feature\n* fix\nScope must be one of the following:\n* common\n* core\n* elements\n* forms\n* http \ntitlePolicy:\ntitleRegex: r/\\b(build|ci|docs|feature|fix)\\b\\s*\\((common|core|elements|forms|http)\\):\\s*\\w+.*/\n
Download this example as a CM file."},{"location":"automations/standard/enforce-pr-title/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/explain-code-experts/","title":"Explain Code Experts","text":"Post a comment that uses git blame and history to list the most relevant experts for all PRs. The comment will automatically update as additional commits are added to the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
Explain Code Experts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nexplain_code_experts:\nif:\n- {{ pr.labels | match(term='suggest-reviewer') | some }}\nrun:\n- action: explain-code-experts@v1 args:\ngt: 10
Download this example as a CM file."},{"location":"automations/standard/explain-code-experts/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/label-management/","title":"PR Label Management with gitStream","text":"Use YAML to automate label management on your git repo with gitStream.
"},{"location":"automations/standard/label-management/#enforce-required-labels","title":"Enforce Required Labels","text":"Automatically enforce the use of required PR labels.
Configuration Description
Conditions (all must be true):
Automation Actions:
Missing Required Labels
label.Enforce Required Labels
manifest:\nversion: 1.0\nautomations:\nenforce_required_labels:\nif:\n- {{ pr.labels | match(list=['Core', 'Mobile', 'UI']) | nope }}\nrun:\n- action: request-changes@v1\nargs:\ncomment: Please ensure that your PR is labeled with either 'Core', 'Mobile', or 'UI'. These labels help us to better track and manage your contribution. Thank you.\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/#label-modified-resources","title":"Label Modified Resources","text":"Apply a label to all PRs that indicates what percentage of new lines of code modify one or more specified resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Changed Resources By Percent
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_resource_percent_{{ item.name }}:\nif:\n- {{ files | match(list=item.resources) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.additions | round }}% {{ item.name }}'\n{% endfor %}\nresources:\ncore:\n- src/app\n- src/core\nmobile: - src/android\n- src/ios\ndocs:\n- docs/\nlabels:\n- name: Core\nresources: {{ resources.core }}\nadditions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.core ) | map(attr='additions') | sum / total.additions * 100 }}\n- name: Mobile\nresources: {{ resources.mobile }}\nadditions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.mobile ) | map(attr='additions') | sum / total.additions * 100 }}\n- name: Docs\nresources: {{ resources.docs }}\nadditions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.docs ) | map(attr='additions') | sum / total.additions * 100 }}\ntotal:\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/#label-prs-by-language","title":"Label PRs by Language","text":"Automatically detect which programming languages are contained in PRs and automatically label the PRs appropriately.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label PRs by Language
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_{{ item.name }}_pr:\nif:\n- {{ files | match(regex=item.resources) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.name }}'\n{% endfor %}\nlabels:\n- name: Java\nresources: r/.java$/\n- name: Rust\nresources: r/.rs$/\n- name: HTML\nresources: r/.html$/\n- name: JavaScript\nresources: r/.js$/\n- name: Python\nresources: r/.py$/\n- name: Golang\nresources: r/.go$/\n- name: Ruby\nresources: r/.rb$/\n- name: CSS\nresources: r/.css/\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/#label-the-number-of-unresolved-code-review-threads","title":"Label the Number of Unresolved Code Review Threads","text":"Automatically label PRs when there are unresolved code review comments.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Unresolved Review Threads
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_unresolved_threads: if: - {{ pr.unresolved_threads }}\nrun:\n- action: add-label@v1\nargs:\nlabel: {{ pr.unresolved_threads }} Unresolved Thread(s)\ncolor: {{ colors.yellow }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/#automatically-recommend-labels-for-new-prs","title":"Automatically Recommend Labels for New PRs","text":"Automatically suggest labels to apply to new PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Suggest Labels
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nsuggest_labels: if: - {{ pr.labels | length == 0}}\nrun:\n- action: add-comment@v1\nargs: comment: | All PRs must contain labels that indicate which CI/CD systems must be run. PLease update your PR to include one of the following labels: `Build: Mobile`, `Build: UI`, `Build: All`, `Build: None`\nAdditionally, Here are some labels you can apply to this PR that may be helpful:\n* Suggest Reviewer - Use this if you aren't sure who to assign as the reviewer.\n* WIP - Indicate this is a work in progress that shouldn't be merged.\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/#label-prs-with-the-number-of-approvals","title":"Label PRs with the Number of Approvals","text":"Automatically label PRs with the number of completed reviews that approve the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label the Number of Approvals
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_approvals: if: - {{ pr.approvals | length > 0 }}\nrun:\n- action: add-label@v1\nargs:\nlabel: {{ pr.approvals | length }} Approved Review(s)\n
Download this example as a CM file."},{"location":"automations/standard/label-management/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for help with these examples.
"},{"location":"automations/standard/label-management/enforce-labels/","title":"Enforce Required Labels","text":"Automatically enforce the use of required PR labels.
Configuration Description
Conditions (all must be true):
Automation Actions:
Missing Required Labels
label.Enforce Required Labels
manifest:\nversion: 1.0\nautomations:\nenforce_required_labels:\nif:\n- {{ pr.labels | match(list=['Core', 'Mobile', 'UI']) | nope }}\nrun:\n- action: request-changes@v1\nargs:\ncomment: Please ensure that your PR is labeled with either 'Core', 'Mobile', or 'UI'. These labels help us to better track and manage your contribution. Thank you.\n
Download this example as a CM file."},{"location":"automations/standard/label-management/label-approvals/","title":"Label the Number of Approvals","text":"Automatically label PRs with the number of completed reviews that approve the PR.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label the Number of Approvals
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_approvals: if: - {{ pr.approvals | length > 0 }}\nrun:\n- action: add-label@v1\nargs:\nlabel: {{ pr.approvals | length }} Approved Review(s)\n
Download this example as a CM file."},{"location":"automations/standard/label-management/label-modified-resources/","title":"Label Modified Resourcess Based on Modified Resources","text":"Automatically label PRs to indicate what resources are being changed.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Modified Resources
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_resource_{{ item.name }}:\nif:\n-{{ branch.name | includes(regex=item.branch) or files | match(list=item.resources) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: {{ item.name }}\n{% endfor %}\nlabels:\n- name: Core\nresources:\n- src/app\nbranch: r/^core-/\n- name: mobile\nresources:\n- src/android\n- src/ios\nbranch: r/^mobile-/\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/label-prs-by-language/","title":"Label PRs by Language","text":"Automatically detect which programming languages are contained in PRs and automatically label the PRs appropriately.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label PRs by Language
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_{{ item.name }}_pr:\nif:\n- {{ files | match(regex=item.resources) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.name }}'\n{% endfor %}\nlabels:\n- name: Java\nresources: r/.java$/\n- name: Rust\nresources: r/.rs$/\n- name: HTML\nresources: r/.html$/\n- name: JavaScript\nresources: r/.js$/\n- name: Python\nresources: r/.py$/\n- name: Golang\nresources: r/.go$/\n- name: Ruby\nresources: r/.rb$/\n- name: CSS\nresources: r/.css/\n
Download this example as a CM file. "},{"location":"automations/standard/label-management/label-resources-percent/","title":"Label Changed Resources By Percent","text":"Apply a label to all PRs that indicates what percentage of new lines of code modify one or more specified resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Changed Resources By Percent
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_resource_percent_{{ item.name }}:\nif:\n- {{ files | match(list=item.resources) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.additions | round }}% {{ item.name }}'\n{% endfor %}\nresources:\ncore:\n- src/app\n- src/core\nmobile: - src/android\n- src/ios\ndocs:\n- docs/\nlabels:\n- name: Core\nresources: {{ resources.core }}\nadditions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.core ) | map(attr='additions') | sum / total.additions * 100 }}\n- name: Mobile\nresources: {{ resources.mobile }}\nadditions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.mobile ) | map(attr='additions') | sum / total.additions * 100 }}\n- name: Docs\nresources: {{ resources.docs }}\nadditions: {{ branch.diff.files_metadata | filter(attr='file', list=resources.docs ) | map(attr='additions') | sum / total.additions * 100 }}\ntotal:\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n
Download this example as a CM file."},{"location":"automations/standard/label-management/label-unresolved-threads/","title":"Label Unresolved Review Threads","text":"Automatically label PRs when there are unresolved code review comments.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Unresolved Review Threads
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_unresolved_threads: if: - {{ pr.unresolved_threads }}\nrun:\n- action: add-label@v1\nargs:\nlabel: {{ pr.unresolved_threads }} Unresolved Thread(s)\ncolor: {{ colors.yellow }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"automations/standard/label-management/suggest-labels/","title":"Suggest Labels","text":"Automatically suggest labels to apply to new PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Suggest Labels
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nsuggest_labels: if: - {{ pr.labels | length == 0}}\nrun:\n- action: add-comment@v1\nargs: comment: | All PRs must contain labels that indicate which CI/CD systems must be run. PLease update your PR to include one of the following labels: `Build: Mobile`, `Build: UI`, `Build: All`, `Build: None`\nAdditionally, Here are some labels you can apply to this PR that may be helpful:\n* Suggest Reviewer - Use this if you aren't sure who to assign as the reviewer.\n* WIP - Indicate this is a work in progress that shouldn't be merged.\n
Download this example as a CM file."},{"location":"automations/standard/link-issue-tracker/","title":"Automatic Project Tracker Links","text":"Post a PR comment that links the associated resource in your issue tracker, such as Jira, Azure Boards, Shortcut, Asana, and more.
Configuration Description
Conditions (all must be true):
Automation Actions:
Link Issue Tracker
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Configure these to match your organization.\nprovider: jira\norgName: org\nasanaProject: 1234\nazureProject: my_project\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\ncomment_issue_tracker:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\njira:\nbaseurl: https://[orgName].atlassian.net/browse/\npattern: r/\\b[A-Za-z]+-\\d+\\b/\nasana:\nbaseurl: https://app.asana.com/0/[asanaProject]/0/\npattern: r/asana-(\\d+)/\nazure:\nbaseurl: https://dev.azure.com/[orgName]/[azureProject]/_workitems/\npattern: r/(\\w+)-(\\w+)-(\\d+)/\nshortcut:\nbaseurl: https://app.shortcut.com/[orgName]/story/\npattern: r/(\\w+)\\/sc-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"automations/standard/review-assignment/","title":"Use gitStream for Automatic Code Review Assignment","text":"Automatically assign code reviews based on changed resources, code expertise, branch, and more.
"},{"location":"automations/standard/review-assignment/#assign-code-experts","title":"Assign Code Experts","text":"When someone applies a suggest-reviewers
label to a PR, use codeExperts to assign recommended reviewers and post a comment with the explainCodeExperts
automation action.
Configuration Description
Conditions (all must be true):
Automation Actions:
codeExperts
to assign recommended reviewers.explainCodeExperts
to post a comment that lists the top code experts for the PR.Assign Code Experts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nassign_code_experts:\n# Triggered when someone applies a suggest-reviewer label to a PR.\nif: - {{ pr.labels | match(term='suggest-reviewer') | some }}\n# More info about code experts\n# https://docs.gitstream.cm/filter-functions/#codeexperts\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=10) }}\n- action: explain-code-experts@v1 args:\ngt: 10
Download this example as a CM file. "},{"location":"automations/standard/review-assignment/#branch-based-review-policies","title":"Branch-Based Review Policies","text":"Automatically route and manage PRs based on the target or destination branch.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Target Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in branches %}\nreview_target_branch_{{ item.name }}: if: - {{ pr.target| match(regex=item.prefix) }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: {{ item.reviews }}\n- action: add-comment@v1\nargs: comment: | PRs to the {{ item.name }} branch require {{ item.reviews }} review(s).\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ item.reviewers }}]\n{% endfor %}\nbranches:\n- prefix: r/^release/ reviews: 4\nname: Release\n- prefix: r/^experimental-/ reviews: 1\nname: Experimental\n
Download this example as a CM file. Review Source Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in branches %}\nreview_source_branch{{ item.name }}: if: - {{ branch.name | match(regex=item.prefix) }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: {{ item.reviews }}\n- action: add-comment@v1\nargs: comment: | Reviewers from the {{ item.name }} team have automatically been assigned to this PR.\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ item.reviewers }}]\n{% endfor %}\nbranches:\n- prefix: r/^ABC/ reviewers: org/a-team\nname: ABC\n- prefix: r/^XYZ-/ reviewers: org/x-team\nname: XYZ\n
Download this example as a CM file. "},{"location":"automations/standard/review-assignment/#review-sensitive-files","title":"Review Sensitive Files","text":"Compare the changed files to a pre-defined list of files and directories in. If any files match, require a review from the team my-organization/security
.
Configuration Description
Conditions (all must be true):
sensitive_files
custom expression. Customize this list for your project.Automation Actions:
my-organization/security
to review the PR. Customize this value to match your organization.Review Sensitive Files
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Assign special teams to review sensitive files. \n# This requires the `sensitive` custom expression found at the bottom of this file.\nreview_sensitive_files:\n# For all files listed in the sensitive custom expression.\nif:\n- {{ files | match(list=sensitive_files) | some }}\nrun:\n# Add reviewers from the dev-leads team, and require two approvals\n# Modify `my-organization/security` to match your organization.\n- action: add-reviewers@v1\nargs:\nreviewers: [my-organization/security]\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR affects one or more sensitive files and requires review from the security team.\n# The `sensitive_file_review` automation requires this custom expression.\n# Modify this list to suit your security needs.\nsensitive_files:\n- src/app/auth/\n- src/app/routing/\n- src/app/resources/\n
Download this example as a CM file. "},{"location":"automations/standard/review-assignment/#custom-team-review-policies","title":"Custom Team Review Policies","text":"Automatically assign the PR author's team to review PRs.
Configuration Description
Conditions (all must be true):
teams
custom expression.Automation Actions:
Assign the Author's Team for Review
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in teams %}\nreview_team_{{ item.name }}: if: - {{ pr.author_teams | match(regex=item.regex) }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ item.team }}] - action: add-comment@v1\nargs: comment: | This {{ item.name }} team has been automatically assigned to review this PR.\n{% endfor %}\nteams:\n- regex: r/ui-team/\nname: UI Team\nteam: org/ui-team\n- regex: r/mobile-team/\nname: Mobile\nteam: org/mobile-team\n
Download this example as a CM file. "},{"location":"automations/standard/review-assignment/#distribute-code-reviews-to-share-knowledge","title":"Distribute Code Reviews to Share Knowledge","text":"Require the reviewer as a previous contributor with code expertise between set thresholds when PR contains Share Knowledge
label.
Configuration Description
Conditions (all must be true):
Share Knowledge
label has been applied to the PRAutomation Actions:
Knowledge Share
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nshare_knowledge:\nif:\n- {{ pr.labels | match(term='Share Knowledge') | some }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=30, lt=60) | random }}\n- action: add-comment@v1\nargs:\ncomment: |\ngitStream has assigned a reviewer to increase knowledge sharing on this PR.\n
Download this example as a CM file. "},{"location":"automations/standard/review-assignment/#notify-watcher","title":"Notify Watcher","text":"Automatically notify code reviewers based on a resource watchlist.
Configuration Description
Conditions (all must be true):
watchers
custom expression.Automation Actions:
Notify Watcher
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n## change orgName to match your git organization name.\norgName: company\nautomations:\n{% for item in watchers %}\nnotify_watcher_{{ item.owner if item.owner else item.team }}:\nif:\n- {{ (files | match(list=item.files) | some) or (source.diff.files | match(attr=\"diff\", list=item.diffs) | some) }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\n@{{ item.owner if item.owner else ([\"{{ orgName }}/\", item.team] | join) }} - this PR has changes you're watching\n{% if files | match(list=item.files) | some -%}\nfiles:\n{%- for file in files | filter(list=item.files) %}\n- {{ file }}\n{%- endfor -%}\n{%- endif %}\n{% if source.diff.files | match(attr=\"diff\", list=item.diffs) | some -%}\ndiffs:\n{%- for diff in item.diffs -%}\n{%- if source.diff.files | match(attr=\"diff\", list=diff) | some %}\n- {{ diff }}\n{%- for file in source.diff.files | filter(attr=\"diff\", list=diff) | map(attr=\"new_file\") %}\n- {{ file }}\n{%- endfor -%}\n{%- endif -%}\n{%- endfor -%}\n{%- endif %}\n- action: add-reviewers@v1\nargs:\nreviewers: {{ item.owner }}\nteam_reviewers: {{ item.team }}\n{% endfor %}\nwatchers:\n- owner: juliaspencer\nfiles:\n- src/auth\n- team: release\nfiles:\n- package.json\n- yarn.lock\n
Download this example as a CM file."},{"location":"automations/standard/review-assignment/assign-code-experts/","title":"Assign Code Experts","text":"When someone applies a suggest-reviewers
label to a PR, use codeExperts to assign recommended reviewers and post a comment with the explainCodeExperts
automation action.
Configuration Description
Conditions (all must be true):
Automation Actions:
codeExperts
to assign recommended reviewers.explainCodeExperts
to post a comment that lists the top code experts for the PR.Assign Code Experts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nassign_code_experts:\n# Triggered when someone applies a suggest-reviewer label to a PR.\nif: - {{ pr.labels | match(term='suggest-reviewer') | some }}\n# More info about code experts\n# https://docs.gitstream.cm/filter-functions/#codeexperts\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=10) }}\n- action: explain-code-experts@v1 args:\ngt: 10
Download this example as a CM file."},{"location":"automations/standard/review-assignment/assign-code-experts/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-assignment/notify-watcher/","title":"Notify Watchlist","text":"Automatically notify code reviewers based on a resource watchlist.
Configuration Description
Conditions (all must be true):
watchers
custom expression.Automation Actions:
Notify Watcher
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n## change orgName to match your git organization name.\norgName: company\nautomations:\n{% for item in watchers %}\nnotify_watcher_{{ item.owner if item.owner else item.team }}:\nif:\n- {{ (files | match(list=item.files) | some) or (source.diff.files | match(attr=\"diff\", list=item.diffs) | some) }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\n@{{ item.owner if item.owner else ([\"{{ orgName }}/\", item.team] | join) }} - this PR has changes you're watching\n{% if files | match(list=item.files) | some -%}\nfiles:\n{%- for file in files | filter(list=item.files) %}\n- {{ file }}\n{%- endfor -%}\n{%- endif %}\n{% if source.diff.files | match(attr=\"diff\", list=item.diffs) | some -%}\ndiffs:\n{%- for diff in item.diffs -%}\n{%- if source.diff.files | match(attr=\"diff\", list=diff) | some %}\n- {{ diff }}\n{%- for file in source.diff.files | filter(attr=\"diff\", list=diff) | map(attr=\"new_file\") %}\n- {{ file }}\n{%- endfor -%}\n{%- endif -%}\n{%- endfor -%}\n{%- endif %}\n- action: add-reviewers@v1\nargs:\nreviewers: {{ item.owner }}\nteam_reviewers: {{ item.team }}\n{% endfor %}\nwatchers:\n- owner: juliaspencer\nfiles:\n- src/auth\n- team: release\nfiles:\n- package.json\n- yarn.lock\n
Download this example as a CM file."},{"location":"automations/standard/review-assignment/notify-watcher/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-assignment/review-branch/","title":"Branch-Based Review Policies","text":"Automatically route and manage PRs based on the target or destination branch.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Target Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in branches %}\nreview_target_branch_{{ item.name }}: if: - {{ pr.target| match(regex=item.prefix) }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: {{ item.reviews }}\n- action: add-comment@v1\nargs: comment: | PRs to the {{ item.name }} branch require {{ item.reviews }} review(s).\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ item.reviewers }}]\n{% endfor %}\nbranches:\n- prefix: r/^release/ reviews: 4\nname: Release\n- prefix: r/^experimental-/ reviews: 1\nname: Experimental\n
Download this example as a CM file. Review Source Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in branches %}\nreview_source_branch{{ item.name }}: if: - {{ branch.name | match(regex=item.prefix) }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: {{ item.reviews }}\n- action: add-comment@v1\nargs: comment: | Reviewers from the {{ item.name }} team have automatically been assigned to this PR.\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ item.reviewers }}]\n{% endfor %}\nbranches:\n- prefix: r/^ABC/ reviewers: org/a-team\nname: ABC\n- prefix: r/^XYZ-/ reviewers: org/x-team\nname: XYZ\n
Download this example as a CM file. "},{"location":"automations/standard/review-assignment/review-branch/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-assignment/review-sensitive-files/","title":"Review Sensitive Files","text":"Compare the changed files to a pre-defined list of files and directories in. If any files match, require a review from the team my-organization/security
.
Configuration Description
Conditions (all must be true):
sensitive_files
custom expression. Customize this list for your project.Automation Actions:
my-organization/security
to review the PR. Customize this value to match your organization.Review Sensitive Files
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Assign special teams to review sensitive files. \n# This requires the `sensitive` custom expression found at the bottom of this file.\nreview_sensitive_files:\n# For all files listed in the sensitive custom expression.\nif:\n- {{ files | match(list=sensitive_files) | some }}\nrun:\n# Add reviewers from the dev-leads team, and require two approvals\n# Modify `my-organization/security` to match your organization.\n- action: add-reviewers@v1\nargs:\nreviewers: [my-organization/security]\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR affects one or more sensitive files and requires review from the security team.\n# The `sensitive_file_review` automation requires this custom expression.\n# Modify this list to suit your security needs.\nsensitive_files:\n- src/app/auth/\n- src/app/routing/\n- src/app/resources/\n
Download this example as a CM file."},{"location":"automations/standard/review-assignment/review-sensitive-files/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-assignment/review-team/","title":"Assign the Author's Team for Review","text":"Automatically assign the PR author's team to review PRs.
Configuration Description
Conditions (all must be true):
teams
custom expression.Automation Actions:
Assign the Author's Team for Review
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in teams %}\nreview_team_{{ item.name }}: if: - {{ pr.author_teams | match(regex=item.regex) }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [{{ item.team }}] - action: add-comment@v1\nargs: comment: | This {{ item.name }} team has been automatically assigned to review this PR.\n{% endfor %}\nteams:\n- regex: r/ui-team/\nname: UI Team\nteam: org/ui-team\n- regex: r/mobile-team/\nname: Mobile\nteam: org/mobile-team\n
Download this example as a CM file."},{"location":"automations/standard/review-assignment/review-team/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-assignment/share-knowledge/","title":"Knowledge Share","text":"Require the reviewer as a previous contributor with code expertise between set thresholds when PR contains Share Knowledge
label.
Configuration Description
Conditions (all must be true):
Share Knowledge
label has been applied to the PRAutomation Actions:
Knowledge Share
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nshare_knowledge:\nif:\n- {{ pr.labels | match(term='Share Knowledge') | some }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: {{ repo | codeExperts(gt=30, lt=60) | random }}\n- action: add-comment@v1\nargs:\ncomment: |\ngitStream has assigned a reviewer to increase knowledge sharing on this PR.\n
Download this example as a CM file."},{"location":"automations/standard/review-assignment/share-knowledge/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-changelog/","title":"Enforce Changelog Updates","text":"Request changes if a PR that meets specified criteria lacks an update to the project's changelog.
Configuration Description
Conditions (All must be true):
feature
Automation Actions:
\u26a0\ufe0f Missing Changelog
Review Changelog
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Request changes for new features that lack changelog updates.\nreview_changelog: if: - {{ branch.name | includes(term=\"feature\") }}\n- {{ files | match(regex=r/^docs\\/changelog\\.md$/) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Changelog\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | All new features require an update to the changelog. Please modify your PR to include any relevant changelog updates.\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. Special thanks to Boemo W Mmopelwa for providing this example.
"},{"location":"automations/standard/review-changelog/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/standard/review-todo-comments/","title":"Review TODO Comments","text":"Request changes for a PR that contains a TODO statement.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review TODO Comments
manifest:\nversion: 1.0\nautomations:\nreview_todo_comments:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/(TODO)|(todo)/) | some }}\nrun: - action: request-changes@v1\nargs:\ncomment: | This PR contains a TODO statement. Please check to see if they should be removed.\n
Download this example as a CM file."},{"location":"automations/standard/summarize-language-changes/","title":"Summarize Language Changes","text":"Post a comment that summarizes which programming languages are contained in PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Summarize Language Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non: - pr_created\nautomations:\nsummarize_language_changes:\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: <h3>Summary of Changes by Language</h3>\n<table>\n<tr>\n<td>Language</td>\n<td>Language Change Percentage</td>\n</tr>\n<tr>\n<td>Java</td>\n<td>{{ total.java | round }}%</td>\n</tr>\n<tr>\n<td>JavaScript</td>\n<td>{{ total.javascript | round }}%</td>\n</tr>\n<td>Rust</td>\n<td>{{ total.rust | round }}%</td>\n</tr>\n<tr>\n<td>Ruby</td>\n<td>{{ total.ruby | round }}%</td>\n</tr>\n<td>HTML</td>\n<td>{{ total.html | round }}%</td>\n</tr>\n<td>CSS</td>\n<td>{{ total.css | round }}%</td>\n</tr>\n<tr>\n<td>Golang</td>\n<td>{{ total.golang | round }}%</td>\n</tr>\n<tr>\n<td>Python</td>\n<td>{{ total.python | round }}%</td>\n</tr>\n</table>\ntotal:\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\njava: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.java$/ ) | map(attr='additions') | sum / total.additions * 100 }}\njavascript: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.js$/ ) | map(attr='additions') | sum / total.additions * 100 }}\nrust: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.rs$/ ) | map(attr='additions') | sum / total.additions * 100 }}\nruby: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.rb$/ ) | map(attr='additions') | sum / total.additions * 100 }}\nhtml: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.html$/ ) | map(attr='additions') | sum / total.additions * 100 }}\ncss: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.css$/ ) | map(attr='additions') | sum / total.additions * 100 }}\ngolang: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.go$/ ) | map(attr='additions') | sum / total.additions * 100 }}\npython: {{ branch.diff.files_metadata | filter(attr='file', regex=r/.py$/ ) | map(attr='additions') | sum / total.additions * 100 }}\n
Download this example as a CM file."},{"location":"automations/standard/summarize-language-changes/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/utilities/cm-header/","title":"CM File Header","text":"This header is useful to add to the top of any configuration files you create for your organization. This will help others who want to make improvements to your configurations in the future.
CM File Header
# -*- mode: yaml -*-\n# +----------------------------------------------------------------------------+\n# | WARNING: This file controls repo automations, use caution when modifying |\n# +----------------------------------------------------------------------------+\n# | This file contains one or more /:\\ gitStream automations: |\n# | https:// docs.gitstream.cm |\n# | |\n# | gitStream uses YAML syntax with nunjucks templating via Jinja 2. |\n# | |\n# | Automations follow an \"if this, then that\" execution format. |\n# | More info here: https://docs.gitstream.cm/how-it-works/ |\n# | |\n# +----------------------------------------------------------------------------+\n# /:\\ gitStream Reference Docs: \n# Context Variables: https://docs.gitstream.cm/context-variables/\n# Filter Functions: https://docs.gitstream.cm/filter-functions/\n# Automation Actions: https://docs.gitstream.cm/automation-actions/\n
Download this example as a CM file. "},{"location":"automations/utilities/cm-header/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/utilities/colors-custom-expression/","title":"Colors Custom Expression","text":"This automation demonstrates all of GitHub's default label colors, implemented as a colors
custom expression. This is meant to help improve other automations rather than being used on its own.
Colors Custom Expression
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# This automation demonstrates all of GitHub's default label colors.\n# This is meant to be used as a reference, not as an automation in your repo.\nautomations:\nlabel_colors:\nif:\n- true\nrun:\n- action: add-label@v1\nargs:\nlabel: \"Test Label\"\ncolor: {{ colors.green }}\n# These are all of the colors in GitHub's default label color palette.\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\ngreen: '0e8a16'\nteal: '006b75'\nblue: '1d76db'\ndark-blue: '0052cc'\npurple: '5319e7'\nlight-red: 'e99695'\nlight-orange: 'f9d0c4'\nlight-yellow: 'fef2c0'\nlight-green: 'c2e0c6'\nlight-teal: 'bfdadc'\nlight-blue: 'c5def5'\nlight-dark-blue: 'bfd4f2'\nlight-purple: 'd4c5f9'\n
Download this example as a CM file. "},{"location":"automations/utilities/colors-custom-expression/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"automations/welcome-newcomer/","title":"Welcome Newcomer","text":"Post a welcome message when someone makes their first PR to a repo, and provide context to help them know what's next.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/mentors
team to review the PR. Customize this to match your organization.new-contributor
label to the PR.Welcome Newcomer
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Help newcomers find mentors to guide them.\nwelcome_newcomer:\n# If the PR author made their first contirbution on the current day\nif:\n- {{ repo.author_age < 1 and repo.age > 0 }}\n# 1. Add reviewers from the team `my_organization/mentors`. Replace this string to match your organization\n# 2. Apply a new-contributor label.\n# 3 Post a comment that explains the next steps.\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [my_organization/mentors]\n- action: add-label@v1\nargs:\nlabel: 'new-contributor'\ncolor: '#FBBD10'\n- action : add-comment@v1\nargs:\ncomment: |\nHello {{ pr.author }} \ud83d\udc4b Thanks for making your first PR, and welcome to our project!\nOur mentor team has automatically been assigned to review this PR and guide you through the process.\nPlease reach out to that team if you have questions about the next steps.\n
Download this example as a CM file."},{"location":"automations/welcome-newcomer/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/","title":"gitStream Integrations","text":"LinearB
"},{"location":"integrations/#github-gitlab","title":"GitHub / GitLab","text":":: GitHub Actions
:: GitHub Copilot
PR Labels
Branch Management
PR Reviews
"},{"location":"integrations/#security","title":"Security","text":"Jit
SonarCloud
Dependabot
"},{"location":"integrations/#project-management","title":"Project Management","text":"Jira
Asana
Shortcut
Azure Boards
"},{"location":"integrations/#languages","title":"Languages","text":"JavaScript
Go
Python
Java
Ruby
HTML/CSS
Rust
"},{"location":"integrations/#documentation","title":"Documentation","text":"Swimm
Javadoc
JSDoc
RDoc
Godoc
"},{"location":"integrations/#other","title":"Other","text":"Terraform
"},{"location":"integrations/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
"},{"location":"integrations/asana/","title":"Integrate gitStream with Asana","text":"Learn how to integrate gitStream with Asana
"},{"location":"integrations/asana/#label-missing-asana-info","title":"Label Missing Asana Info","text":"Automatically label PRs that are missing references to Asana resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Asana Link
labelLabel Missing Asana
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_asana:\nif:\n- {{not (has.asana.ticket_in_title or has.asana.ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Asana Link\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated Asana resource.\nhas:\nasana:\nticket_in_title: {{ pr.title | includes(regex=r/asana-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/app\\.asana.\\com\\/(\\d+)\\/(\\d+)\\/(\\d+)\\/(\\d+)\\/(\\d+)/) }}\ncolors:\nred: 'b60205'\n
Download this example as a CM file. "},{"location":"integrations/asana/#automatically-link-prs-to-related-asana-cards","title":"Automatically Link PRs to Related Asana Cards","text":"Provide automatic links to Asana cards that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Asana Card
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nprovider: asana\n# Configure this to match your organization. It is used in tracker.asana.baseurl.\nasanaProject: 1234\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_asana:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\nasana:\nbaseurl: https://app.asana.com/0/[asanaProject]/0/\npattern: r/asana-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"integrations/asana/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/azure-boards/","title":"Integrate gitStream with Azure Boards","text":"Learn how to integrate gitStream with Azure Boards.
"},{"location":"integrations/azure-boards/#label-missing-azure-boards-info","title":"Label Missing Azure Boards Info","text":"Automatically label PRs that are missing references to Azure Boards resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Azure Boards Link
labelLabel Missing Azure Boards
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_azure:\nif:\n- {{not (has.azure.ticket_in_title or has.azure.ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Azure Boards Link\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated resource in Azure Boards.\nhas:\nazure:\nticket_in_title: {{ pr.title | includes(regex=r/(\\w+)-(\\w+)-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/(dev\\.azure\\.com|(\\w+)\\.visualstudio\\.com)\\/(\\w+)\\/(\\w+)\\/_workitems\\/edit\\/(\\d+)/) }}\ncolors:\nred: 'b60205'\n
Download this example as a CM file. "},{"location":"integrations/azure-boards/#automatically-link-prs-to-related-azure-boards-resources","title":"Automatically Link PRs to Related Azure Boards Resources","text":"Provide automatic links to Azure Boards resources that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Azure Boards Resource
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Configure these to match your organization.\nprovider: azure\n# The name of your Azure organization\norgName: org\n# The name of your Azure project\nazureProject: my_project\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_azure_boards:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\nazure:\nbaseurl: https://dev.azure.com/[orgName]/[azureProject]/_workitems/\npattern: r/(\\w+)-(\\w+)-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"integrations/azure-boards/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/dependabot/","title":"Integrate gitStream with Dependabot","text":""},{"location":"integrations/dependabot/#approve-and-merge-dependabot-changes","title":"Approve and Merge Dependabot Changes","text":"Approve PRs from Dependabot
Conditions (all must be true):
Automation Actions:
approved-dependabot
label to the PRApprove Dependabot
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_dependabot:\nif:\n- {{ branch.name | includes(term=\"dependabot\") }}\n- {{ branch.author | includes(term=\"dependabot\") }}\nrun:\n- action: approve@v1\n- action: add-label@v1\nargs:\nlabel: \"approved-dependabot\"\n- action: merge@v1\nargs:\nwait_for_all_checks: true\nsquash_on_merge: true\n
Download this example as a CM file. "},{"location":"integrations/github-actions/","title":"Integrate gitStream with GitHub Actions","text":""},{"location":"integrations/github-actions/#dispatch-github-actions","title":"Dispatch GitHub Actions","text":"Automatically trigger GitHub Actions based on PR content like changed resources, source or target branch, slash commands, and more.
By BranchUsing LabelsBy Modified ResourcesConfiguration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions by Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\nautomations:\n{% for item in pipelines %}\n# Change pr.target to branch.name if you want to trigger on the source branch rather then the target branch.\ndispatch_github_action_{{ item.name }}:\nif:\n- {{ pr.target | includes(term=item.branch_prefix) }}\nrun:\n- action: run-github-workflow@v1\nargs:\nworkflow: .github/workflows/{{ item.workflow }}\ncheck_name: {{ item.name }}\n- action: add-label@v1\nargs:\nlabel: {{ item.label }}\n{% endfor %}\npipelines:\n- name: mobile_ci\nlabel: Mobile CI branch_prefix: 'mobile-'\nworkflow: mobile.yml\n- name: backend_ci\nlabel: Backend CI branch_prefix: 'backend-'\nworkflow: 'backend.yml'\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Using Labels
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- label_added\n- label_removed\nautomations:\n{% for item in pipelines %}\ndispatch_github_action_{{ item.name }}:\nif:\n- {{ pr.labels | match(term=item.label) | some }}\nrun:\n- action: run-github-workflow@v1\nargs:\nworkflow: .github/workflows/{{ item.workflow }}\ncheck_name: {{ item.name }}\n{% endfor %}\npipelines:\n- name: mobile-ci\nlabel: Mobile CI workflow: mobile.yml\n- name: backend-ci\nlabel: Backend CI workflow: 'backend.yml'\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Dispatch GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\nautomations:\n{% for item in pipelines %}\ndispatch_github_action_{{ item.name }}:\nif:\n- {{ files | match(list=item.resources) | some }}\nrun:\n- action: run-github-workflow@v1\nargs:\nworkflow: .github/workflows/{{ item.workflow }}\ncheck_name: {{ item.name }}\n- action: add-label@v1\nargs:\nlabel: {{ item.label }}\n{% endfor %}\npipelines:\n- name: mobile-ci\nlabel: Mobile CI resources:\n- 'src/android/'\n- 'src/ios/'\nworkflow: mobile.yml\n- name: backend-ci\nlabel: Backend CI resources:\n- 'src/api/'\n- 'src/services'\nworkflow: 'backend.yml'\n- name: frontend-ci\nlabel: Frontend CI\nresources:\n- 'src/app/'\nworkflow: 'frontend.yml'\n
Download this example as a CM file. "},{"location":"integrations/github-actions/#skip-github-actions","title":"Skip GitHub Actions","text":"Automatically skip GitHub Actions based on branch names, modified resource, slash commands, and more.
Prerequisite Config for Required Statuses
If you want to skip a required status check, you will need to make sure that your branch protection is configured to allow gitStream to bypass status check requirements.
By BranchUsing LabelsBy Modified ResourceConfiguration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions by Branch
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\n# Optionally, you can change pr.target to branch.name \n# if you want to trigger based on the source branch name rather then the target branch name.\nautomations:\nskip_github_action_branch:\nif:\n- {{ pr.target | includes(term='release') }}\nrun:\n- action: add-github-check@v1\nargs:\ncheck_name: staging-ci\nconclusion: skipped\n- action: add-comment@v1\nargs:\ncomment: |\n[gitStream](https://docs.gitstream.cm) automatically skipped staging CI pipelines because this PR targets the release branch.\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Use Labels to Automatically Skip GitHub Actions
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- label_added\n- label_removed\nautomations:\nskip_github_action_label:\nif:\n- {{ pr.labels | match(term='experimental') | some }}\nrun:\n- action: add-github-check@v1\nargs:\ncheck_name: production-ci\nconclusion: skipped\n- action: add-comment@v1\nargs:\ncomment: |\n[gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this is labeled for experimental release.\n
Download this example as a CM file. Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Skip GitHub Actions Based on Modified Resources
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\n- commit\nautomations:\nskip_github_action_resource:\nif:\n- {{ files | match(term='docs/') | every }}\nrun:\n- action: add-github-check@v1\nargs:\ncheck_name: release-ci\nconclusion: skipped\n- action: add-github-check@v1\nargs:\ncheck_name: mobile-ci\nconclusion: skipped\n- action: add-comment@v1\nargs:\ncomment: |\n[gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this PR only contains docs changes.\n
Download this example as a CM file. "},{"location":"integrations/github-actions/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/github-copilot/","title":"Integrate gitStream with GitHub Copilot","text":""},{"location":"integrations/github-copilot/#automatically-label-copilot-assisted-prs","title":"Automatically Label Copilot-Assisted PRs","text":"Automatically apply labels to PRs that are assisted by GitHub Copilot. You can apply labels based on a known list of Copilot users, PR tags, or by prompting the PR author to indicate if they used Copilot.
Label by Known UsersLabel by TagLabel by PromptAutomatically apply labels to PRs that are created by known users of generative AI coding tools.
Configuration Description
Conditions:
Automation Actions:
\ud83e\udd16 Copilot
label to the PRLabel by Contributors
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_genai:\n# For all PRs authored by someone who is specified in the genai_contributors list\nif:\n- {{ pr.author | match(list=genai_contributors) | some }}\n# Apply a label indicating the user has adopted Copilot\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\ngenai_contributors:\n- username1\n- username2\n- etc\n
Download this example as a CM file. Look for a specific tag in the PR title, description, comments or commit messages and if found add a label to the PR
Configuration Description
Conditions:
#copilot#
tag is found in any of the PR title, description, comments or commit messages for commits in the PRAutomation Actions:
\ud83e\udd16 Copilot
label to the PRLabel Copilot by Tag
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_copilot:\n# Detect PRs that contain the text '#copilot#' in the title, description, comments, or commit messages\nif:\n- {{ copilot_tag.pr_title or copilot_tag.pr_desc or copilot_tag.pr_comments or copilot_tag.commit_messages }}\n# Apply a label indicating the user has adopted Copilot\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\ncopilot_tag:\npr_title: {{ pr.title | includes(regex=r/#copilot#/) }}\npr_desc: {{pr.description | includes(regex=r/#copilot#/) }}\npr_comments: {{ pr.comments | map(attr='content') | match(regex=r/#copilot#/) | some }}\ncommit_messages: {{ branch.commits.messages | match(regex=r/#copilot#/) | some }}\n
Download this example as a CM file. Prompt PR authors to indicate if they used Copilot for the PR and automatically label the PR if they did. This requires two separate automation files to handle posting the prompt and labeling accordingly.
Configuration Description
Conditions:
Automation Actions:
Ask the PR author about Copilot usage.
-*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\nautomations:\ncomment_copilot_prompt:\n# Post a comment for all PRs to prompt the PR author to indicate whether they used Copilot to assist coding in this PR\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nPlease mark whether you used Copilot to assist coding in this PR\n- [ ] Copilot Assisted\n- [ ] Not Copilot Assisted\n
Download this example as a CM file. Configuration Description
Conditions:
Automation Actions:
\ud83e\udd16 Copilot
label to the PR Label PRs where the user indicated Copilot usage
-*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- comment_added\n- commit\n- merge\nautomations:\n# You should use this automation in conjunction with comment_copilot_prompt.cm\nlabel_copilot_pr:\n# If the PR author has indicated that they used Copilot to assist coding in this PR, \n# apply a label indicating the PR was supported by Copilot\nif:\n- {{ pr.comments | filter(attr='commenter', term='gitstream-cm') | filter (attr='content', regex=r/\\- \\[x\\] Copilot Assisted/) | some}}\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\n
Download this example as a CM file. "},{"location":"integrations/github-copilot/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/godoc/","title":"Integrate gitStream with Godoc","text":""},{"location":"integrations/godoc/#review-godoc-changes","title":"Review Godoc Changes","text":"Approve PRs that only contain changes to Godoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
\ud83d\udcd3 Godoc Only
labelReview Godoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Assign PRs that only affect godocs to the technical writing team and add docs label\nreview_godoc:\nif:\n- {{ source.diff.files | match(attr='diff', regex=r/^\\/\\/.*/) | every }}\n- {{ files | extensions | match(regex=r/go/) | every }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3godoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [org/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"integrations/godoc/#enforce-godoc-requirements-for-new-classes","title":"Enforce Godoc Requirements for New Classes","text":"Require Godoc for all new Golang classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Godoc
label.Enforce Godoc for New Golang Classes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_godoc_new_class: if: - {{ is.go and is.new }} - {{ source.diff.files | match(attr='diff', regex=r/\\/*[\\s\\S]*?\\//) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing godoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | godoc is required for all Golang classes. Please add godoc to all new classes in this PR.\nis:\ngo: {{ files | extensions | match(regex=r/go/) | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"integrations/godoc/#review-godoc-for-large-changes","title":"Review Godoc for Large changes","text":"Require more extensive reviews for large Golang changes that lack Godoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\u26a0\ufe0f Missing Godoc
LabelReview Godoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Golang changes that lack Godoc updates.\nreview_godoc_large:\nif:\n- {{ changes.additions > 100}}\n- {{ source.diff.files | matchDiffLines(regex=r/^\\/\\/.*/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Godoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to Golang classes, but is missing updates to Godoc. Please double check for any necessary Godoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"integrations/godoc/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/javadoc/","title":"Integrate gitStream with Javadoc","text":"Javadoc Examples:
Unblock PRs that only change Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
org/tech-writers
team for optional review. \ud83d\udcd3 Javadoc Only
labelReview Javadoc Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n# Assign PRs that only affect JavaDocs to the technical writing team and add docs label\nreview_javadoc:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | every }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\b(public|protected|private|static|final|synchronized)?\\s+\\w+\\s+\\w+\\s*\\(([^)]*)\\)\\s*\\{/) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3 Javadoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [org/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file. "},{"location":"integrations/javadoc/#review-java-input-parameters-for-javadoc-changes","title":"Review Java Input Parameters for Javadoc Changes","text":"If a PR modifies the input parameters for a Java method, but not the associated Javadocs, notify reviewers to check for Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Javadoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_javadoc_input_parameters: if: - {{ source.diff.files | matchDiffLines(regex=r/\\*\\s@param/) | nope }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\b(public|protected|private|static|final|synchronized)?\\s+\\w+\\s+\\w+\\s*\\(([^)]*)\\)\\s*\\{/) | some }}\nrun:\n- action: add-comment@v1\nargs: comment: | This PR modifies method input parameters, but is missing Javadoc changes. Please check to ensure no Javadoc changes are necessary.\n
Download this example as a CM file. "},{"location":"integrations/javadoc/#review-javadoc-for-large-changes","title":"Review Javadoc for Large Changes","text":"Require more extensive reviews for large Java changes that lack Javadoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/tech-writers
team.\u26a0\ufe0f Missing Javadoc
LabelReview Javadoc for Large Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Java changes that lack Javadoc updates.\nreview_javadoc_large:\nif:\n- {{ changes.ratio > 25}}\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Javadoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n# Sum all the line removed in the PR\ndeletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}\n# Calculate the ratio of new code\nratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. "},{"location":"integrations/javadoc/#enforce-javadoc-requirements-for-new-classes","title":"Enforce Javadoc Requirements for New Classes","text":"Automatically request changes when someone creates a new Java class that lacks Javadoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Javadoc
label.Review Javadoc Requirements for New Classes
manifest:\nversion: 1.0\nautomations:\nreview_new_class_javadoc:\n# Triggered for new Java files that lack Javadoc content.\nif:\n- {{ is.java and is.new }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Javadoc\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: | This PR creates new Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.\nis:\njava: {{ files | extensions | match(term='java') | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/jira/","title":"Integrate gitStream with Jira","text":"Learn how to integrate gitStream with Jira
"},{"location":"integrations/jira/#label-missing-jira-info","title":"Label Missing Jira Info","text":"Label PRs that don't reference a Jira ticket in the title or description. This uses regex to detect Jira ticket formats in the title (e.g. ABC-1234), and URLs to Jira tickets in the description.
Configuration Description
Conditions (all must be true):
Automation Actions:
missing-jira
label.Label Missing Jira Info
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_jira_info:\n# Triggered for PRs that don't have either a Jira ticket number in the title,\n# or a link to a Jira ticket in the PR description.\nif:\n- {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"missing-jira\"\ncolor: 'F6443B'\nhas:\njira_ticket_in_title: {{ pr.title | includes(regex=r/\\b[A-Za-z]+-\\d+\\b/) }}\njira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\\/browse\\/\\w{1,}-\\d{3,4}/) }}\n
Download this example as a CM file. "},{"location":"integrations/jira/#automatically-link-prs-to-related-jira-issues","title":"Automatically Link PRs to Related Jira Issues","text":"Provide automatic links to Jira issues that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Jira Card
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nprovider: jira\n# Change this to the name of your Jira organization\norgName: org\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_jira:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\njira:\nbaseurl: https://[orgName].atlassian.net/browse/\npattern: r/\\b[A-Za-z]+-\\d+\\b/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"integrations/jira/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/jit/","title":"Integrate gitStream with Jit","text":"Included with gitStream Core Functionality
This integration is part of gitStream core functionality, and requires no additional configuration.
Jit Examples:
Manage review assignment for high and medium risk Jit security alerts.
Configuration Description
Review Jit High Alerts
Review Jit Medium Alerts
Review Jit Security Alerts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jit_high_alerts:\nif:\n- {{ jit.metrics.HIGH > 0 }}\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [my-organization/security-team]\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR requires additional review because Jit reported one or more high risk vulnerabilities.\nreview_jit_medium_alerts:\nif:\n- {{ jit.metrics.MEDIUM > 0 }}\nrun:\n- action: set-required-approvals@v1\nargs:\napprovals: 2\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR requires additional reviewers because Jit reported one or more medium risk vulnerabilities.\njit: {{ pr | extractJitFindings }}\n
Download this example as a CM file. "},{"location":"integrations/jit/#review-jit-secret-detection","title":"Review Jit Secret Detection","text":"Close PRs where Jit detects a secret and post a comment explaining steps to remedy the situation.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Security Control
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jit_secret:\nif:\n- true\n- {{ jit.vulnerabilities | match(attr='security_control', term='Secret Detection') | some }}\nrun:\n- action: add-comment@v1\nargs: comment: |\nJit detects secrets in this PR. Please complete the following steps:\n1. Undo the commit with git reset and remove all secrets from the files you modified.\n2. Deactivate the secret in any locations its used and replace it with a new key\n3. Commit your changes and resubmit your PR.\n- action: close@v1\njit: {{ pr | extractJitFindings }}\n
Download this example as a CM file. "},{"location":"integrations/jit/#label-jit-alerts","title":"Label Jit Alerts","text":"Label the number of high, medium, and low risk vulnerabilities Jit reports for PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Jit Alerts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in reports %}\nlabel_jit_{{ item.name }}:\nif:\n- {{ item.count > 0}}\nrun:\n- action: add-label@v1\nargs:\nlabel: 'Jit: {{ item.count }} {{ item.name }} vulnerabilities'\ncolor: {{ colors.red if (item.name == 'high') else (colors.orange if (item.name == 'medium' ) else colors.yellow) }}\n{% endfor %}\njit: {{ pr | extractJitFindings }}\nreports:\n- name: high\ncount: {{ jit.metrics.HIGH }}\n- name: medium\ncount: {{ jit.metrics.MEDIUM }}\n- name: low\ncount: {{ jit.metrics.LOW }}\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\n
Download this example as a CM file. "},{"location":"integrations/jit/#review-jit-ignore-and-accept","title":"Review Jit Ignore and Accept","text":"Notify your Security team when someone ignores a Jit vulnerability report and accepts the risk.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Jit Ignore and Accept
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jit_ignore_accept:\nif:\n- {{ pr.conversations | reject(attr='commenter', term='jit-ci') | filter(attr='content', term='#jit_ignore_accept') | some }}\nrun:\n- action: add-reviewers@v1\nargs:\nreviewers: [my-organziation/security]\n- action: add-label@v1\nargs:\nlabel: '\u2755 Jit: Ignore - Accept Risk'\n- action: add-comment@v1\nargs:\ncomment: |\nThe security team has been assigned for optional review because this PR ignores a Jit alert and accepts the associated risks.\njit: {{ pr | extractJitFindings }}\n
Download this example as a CM file."},{"location":"integrations/jsdoc/","title":"Integrate gitStream with JSDoc","text":"JSDoc Examples:
Approve PRs that only contain changes to JSDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\ud83d\udcd3 JSDoc Only label
Review JSDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Assign PRs that only affect JSDocs to the technical writing team and add docs label\nreview_jsdoc:\nif:\n- {{ source.diff.files | match(attr='diff', regex=r/\\/*\\*[\\s\\S]*?\\//) | every }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3JSDoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file. "},{"location":"integrations/jsdoc/#review-jsdoc-input-parameters","title":"Review JSDoc Input Parameters","text":"Warn PR authors when they change JavaScript function or constructor input parameters without updating JSDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review JSDoc Input Parameters
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jsdoc_input: if: - {{ source.diff.files | matchDiffLines(regex=r/.*\\s@param/) | nope }}\n- {{ source.diff.files | matchDiffLines(regex=r/\\((?:.*\\:.*\\))/) | some }}\nrun:\n- action: add-comment@v1\nargs: comment: | This PR appears to modify method input parameters, but is missing JSDoc changes. Please check to ensure no JSDoc changes are necessary.\n
Download this example as a CM file. "},{"location":"integrations/jsdoc/#review-jsdoc-for-large-changes","title":"Review JSDoc for Large Changes","text":"Require more extensive reviews for large JavaScript changes that lack JSDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\u26a0\ufe0f Missing JSDoc
LabelReview JSDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Javascript changes that lack JSDoc updates.\nreview_jsdoc_large:\nif:\n- {{ changes.ratio > 25}}\n- {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f No JSDoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to JavaScript classes, but is missing updates to JSDoc. Please double check for any necessary JSDoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\n# Sum all the line removed in the PR\ndeletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}\n# Calculate the ratio of new code\nratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. "},{"location":"integrations/jsdoc/#enforce-jsdoc-for-new-javascript-classes","title":"Enforce JSDoc for New JavaScript Classes","text":"Require JSDoc for all new JavaScript classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing JSDoc
label.Enforce JSDoc for New JavaScript Classes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_jsdoc_new_class: if: - {{ is.javascript and is.new }} - {{ source.diff.files | matchDiffLines(regex=r/\\/*\\*([\\s\\S]*?)\\//) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing JSDoc\"\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs: comment: | JSDoc is required for all JavaScript classes. Please add JSDoc to all new classes in this PR.\nis:\njavascript: {{ files | extensions | match(list=['js', 'ts']) | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. Special thanks to Boemo W Mmopelwa for help with these examples.
"},{"location":"integrations/linearb/","title":"Integrate gitStream with LinearB","text":"LinearB is a software delivery management platform that makes it easy to benchmark your engineering organization, track engineering metrics and identify opportunities for improvement.
"},{"location":"integrations/linearb/#track-the-impact-of-generative-ai-initiatives","title":"Track the Impact of Generative AI Initiatives","text":"These examples show how to label PRs that are assisted by GitHub Copilot so you can easily track productivity within LinearB. These examples can be adapted for any other generative AI solutions you might use.
Automatically apply labels to PRs that are assisted by GitHub Copilot. You can apply labels based on a known list of Copilot users, PR tags, or by prompting the PR author to indicate if they used Copilot.
Label by Known UsersLabel by TagLabel by PromptAutomatically apply labels to PRs that are created by known users of generative AI coding tools.
Configuration Description
Conditions:
Automation Actions:
\ud83e\udd16 Copilot
label to the PRLabel by Contributors
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_genai:\n# For all PRs authored by someone who is specified in the genai_contributors list\nif:\n- {{ pr.author | match(list=genai_contributors) | some }}\n# Apply a label indicating the user has adopted Copilot\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\ngenai_contributors:\n- username1\n- username2\n- etc\n
Download this example as a CM file. Look for a specific tag in the PR title, description, comments or commit messages and if found add a label to the PR
Configuration Description
Conditions:
#copilot#
tag is found in any of the PR title, description, comments or commit messages for commits in the PRAutomation Actions:
\ud83e\udd16 Copilot
label to the PRLabel Copilot by Tag
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_copilot:\n# Detect PRs that contain the text '#copilot#' in the title, description, comments, or commit messages\nif:\n- {{ copilot_tag.pr_title or copilot_tag.pr_desc or copilot_tag.pr_comments or copilot_tag.commit_messages }}\n# Apply a label indicating the user has adopted Copilot\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\ncopilot_tag:\npr_title: {{ pr.title | includes(regex=r/#copilot#/) }}\npr_desc: {{pr.description | includes(regex=r/#copilot#/) }}\npr_comments: {{ pr.comments | map(attr='content') | match(regex=r/#copilot#/) | some }}\ncommit_messages: {{ branch.commits.messages | match(regex=r/#copilot#/) | some }}\n
Download this example as a CM file. Prompt PR authors to indicate if they used Copilot for the PR and automatically label the PR if they did. This requires two separate automation files to handle posting the prompt and labeling accordingly.
Configuration Description
Conditions:
Automation Actions:
Ask the PR author about Copilot usage.
-*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- pr_created\nautomations:\ncomment_copilot_prompt:\n# Post a comment for all PRs to prompt the PR author to indicate whether they used Copilot to assist coding in this PR\nif:\n- true\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nPlease mark whether you used Copilot to assist coding in this PR\n- [ ] Copilot Assisted\n- [ ] Not Copilot Assisted\n
Download this example as a CM file. Configuration Description
Conditions:
Automation Actions:
\ud83e\udd16 Copilot
label to the PR Label PRs where the user indicated Copilot usage
-*- mode: yaml -*-\nmanifest:\nversion: 1.0\non:\n- comment_added\n- commit\n- merge\nautomations:\n# You should use this automation in conjunction with comment_copilot_prompt.cm\nlabel_copilot_pr:\n# If the PR author has indicated that they used Copilot to assist coding in this PR, \n# apply a label indicating the PR was supported by Copilot\nif:\n- {{ pr.comments | filter(attr='commenter', term='gitstream-cm') | filter (attr='content', regex=r/\\- \\[x\\] Copilot Assisted/) | some}}\nrun:\n- action: add-label@v1\nargs:\nlabel: '\ud83e\udd16 Copilot'\n
Download this example as a CM file. "},{"location":"integrations/linearb/#label-changes-to-track-in-linearb","title":"Label Changes to Track in LinearB","text":"These examples show how to label PRs based on the changed code so you can more easily compare metrics across languages, frameworks, changed directories, and more.
by Modified Resourceby LanguageAutomatically label PRs to indicate what resources are being changed.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label Modified Resources
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_resource_{{ item.name }}:\nif:\n-{{ branch.name | includes(regex=item.branch) or files | match(list=item.resources) }}\nrun:\n- action: add-label@v1\nargs:\nlabel: {{ item.name }}\n{% endfor %}\nlabels:\n- name: Core\nresources:\n- src/app\nbranch: r/^core-/\n- name: mobile\nresources:\n- src/android\n- src/ios\nbranch: r/^mobile-/\n
Download this example as a CM file. Automatically detect which programming languages are contained in PRs and automatically label the PRs appropriately.
Configuration Description
Conditions (all must be true):
Automation Actions:
Label PRs by Language
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in labels %}\nlabel_{{ item.name }}_pr:\nif:\n- {{ files | match(regex=item.resources) | some }}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.name }}'\n{% endfor %}\nlabels:\n- name: Java\nresources: r/.java$/\n- name: Rust\nresources: r/.rs$/\n- name: HTML\nresources: r/.html$/\n- name: JavaScript\nresources: r/.js$/\n- name: Python\nresources: r/.py$/\n- name: Golang\nresources: r/.go$/\n- name: Ruby\nresources: r/.rb$/\n- name: CSS\nresources: r/.css/\n
Download this example as a CM file. "},{"location":"integrations/linearb/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/rdoc/","title":"Integrate gitStream with RDoc","text":"Integrate gitStream with RDoc: a documentation generation framework for Ruby.
"},{"location":"integrations/rdoc/#review-rdoc-changes","title":"Review RDoc Changes","text":"Approve PRs that only contain changes to RDoc and assign optional reviewers.
Configuration Description
Conditions (all must be true):
Automation Actions:
\ud83d\udcd3 RDoc Only
labelReview RDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_rdoc:\nif:\n- {{ source.diff.files | match(attr='diff', regex=r/^[\\s\\t]*#.*/) | every }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\ud83d\udcd3RDoc Only\"\ncolor: {{ colors.green }}\n- action: add-reviewers@v1\nargs:\nreviewers: [org/tech-writers]\n- action: approve@v1\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file."},{"location":"integrations/rdoc/#enforce-rdoc-requirements-for-new-classes","title":"Enforce RDoc Requirements for New Classes","text":"Require RDoc for all new Ruby classes.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing RDoc
label.Enforce RDoc for New Ruby Classes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_rdoc_new_class: if: - {{ is.rb and is.new }} - {{ source.diff.files | match(attr='diff', regex=r/(\\#.*\\n.*)*def/) | nope }}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing RDoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | RDoc is required for all Ruby classes. Please add documentation for this PR.\nis:\nrb: {{ files | extensions | match(regex=r/rb/) | every }}\nnew: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"integrations/rdoc/#review-rdoc-for-large-changes","title":"Review RDoc for Large changes","text":"Require more extensive reviews for large Ruby changes that lack RDoc updates.
Configuration Description
Conditions (all must be true):
Automation Actions:
ORG/tech-writers
team.\u26a0\ufe0f Missing RDoc
LabelReview RDoc
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n#Require more extensive reviews for large Ruby changes that lack RDoc updates.\nreview_rdoc_large:\nif:\n- {{ changes.additions > 150}}\n- {{ source.diff.files | matchDiffLines(regex=r/(\\#.*\\n.*)*def/) | nope }}\nrun: - action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing RDoc\"\ncolor: {{ colors.yellow }}\n- action: add-comment@v1\nargs: comment: | This PR makes major changes to Ruby methods, but is missing updates to RDoc. Please double check for any necessary RDoc updates.\n- action: add-reviewers@v1\nargs:\nreviewers: [fourth-organization/tech-writers]\nchanges:\n# Sum all the lines added/edited in the PR\nadditions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file."},{"location":"integrations/rdoc/#review-rdoc-for-function-parameter-changes","title":"Review RDoc For Function Parameter Changes","text":"Warn PR authors when they change Ruby function or constructor input parameters without updating RDoc content.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review RDoc Input Parameters
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_rdoc_input: if: - {{ source.diff.files | match(attr='diff', regex=r/(\\#.*\\n.*)*def/) | nope }}\n- {{ source.diff.files | match(attr='diff', regex=r/def.*\\(.*\\)/ | some }}\nrun:\n- action: add-comment@v1\nargs: comment: | This PR modifies method input parameters, but is missing RDoc changes. Please check to ensure no RDoc changes are necessary.\n
Download this example as a CM file."},{"location":"integrations/rdoc/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
More Automations can be found on the Automation Library and Integrations pages.
Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/review-todo-comments/","title":"Automation - Review TODO Comments","text":""},{"location":"integrations/review-todo-comments/#review-todo-comments","title":"Review TODO Comments","text":"Request changes for a PR that contains a TODO statement.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review TODO Comments
manifest:\nversion: 1.0\nautomations:\nreview_todo_comments:\nif:\n- {{ source.diff.files | matchDiffLines(regex=r/(TODO)|(todo)/) | some }}\nrun: - action: request-changes@v1\nargs:\ncomment: | This PR contains a TODO statement. Please check to see if they should be removed.\n
Download this example as a CM file. Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/shortcut/","title":"Integrate gitStream with Shortcut","text":"Learn how to integrate gitStream with Shortcut
"},{"location":"integrations/shortcut/#label-missing-shortcut-info","title":"Label Missing Shortcut Info","text":"Automatically label PRs that are missing references to Shortcut resources.
Configuration Description
Conditions (all must be true):
Automation Actions:
\u26a0\ufe0f Missing Shortcut Link
labelLabel Missing Shortcut
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nlabel_missing_shortcut:\nif:\n- {{not (has.shortcut.ticket_in_title or has.shortcut.ticket_in_desc)}}\nrun:\n- action: add-label@v1\nargs:\nlabel: \"\u26a0\ufe0f Missing Shortcut Link\"\ncolor: {{ colors.red }}\n- action: add-comment@v1\nargs:\ncomment: Please provide a link to the associated Shortcut resource.\nhas:\nshortcut:\nticket_in_title: {{ pr.title | includes(regex=r/(\\w+)\\/sc-(\\d+)/) }}\nticket_in_desc: {{ pr.description | includes(regex=r/(app\\.shortcut\\.com)\\/(\\w+)\\/story\\/(\\d+)\\/(\\w+)/) }}\ncolors:\nred: 'b60205'\n
Download this example as a CM file. "},{"location":"integrations/shortcut/#automatically-link-prs-to-related-shortcut-tasks","title":"Automatically Link PRs to Related Shortcut Tasks","text":"Provide automatic links to Shortcut tasks that are associated with PRs.
Configuration Description
Conditions (all must be true):
Automation Actions:
Automatically Link to the Related Shortcut Task
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Configure these to match your organization.\nprovider: jira\n# Change this to match the name of your Shortcut organization. This is used in tracker.shortcut.baseurl\norgName: org\n{% set ticketid = \"\" %}\n{% for ticket in tickets %}\n{% if (ticket | includes(regex=r/.+/)) %}\n{% set ticketid = ticket %}\n{% endif %}\n{% endfor %} automations:\nlink_shortcut:\nif:\n- {{ has.ticket_in_title or has.ticket_in_branch }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})\nhas:\nticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}\nticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}\ntracker:\nshortcut:\nbaseurl: https://app.shortcut.com/[orgName]/story/\npattern: r/(\\w+)\\/sc-(\\d+)/\ntickets:\n- {{branch.name | capture(regex=tracker[provider].pattern)}}\n- {{pr.title | capture(regex=tracker[provider].pattern)}}\n
Download this example as a CM file."},{"location":"integrations/shortcut/#additional-resources","title":"Additional Resources","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
Related Automations:
More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"integrations/sonar/","title":"Integrate gitStream with SonarCloud","text":"Included with gitStream Core Functionality
This integration is part of gitStream core functionality, and requires no additional configuration.
SonarCloud Examples:
Approve PRs that pass SonarCloud's quality gate.
Configuration Description
Conditions (all must be true):
Automation Actions:
Sonar: Clean Code
label to the PR.Aprove Sonar Clean Code
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_sonar_clean_code:\nif:\n- {{ sonar.bugs.rating == 'A' }}\n- {{ sonar.code_smells.rating == 'A' }}\n- {{ sonar.vulnerabilities.rating == 'A' }}\n- {{ sonar.security_hotspots.rating == 'A' }}\n- {{ sonar.duplications == null or sonar.duplications == 0 }}\nrun: - action: add-label@v1\nargs:\nlabel: '\u2705 Sonar: Clean Code'\ncolor: {{ colors.green }}\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR passes the SonarCloud quality gate check and as been automatically approved.\nsonar: {{ pr | extractSonarFindings }}\ncolors:\ngreen: '0e8a16'\n
Download this example as a CM file. "},{"location":"integrations/sonar/#label-sonarcloud-quality-reports","title":"Label SonarCloud Quality Reports","text":"Label the number of bugs, vulnerabilities, security hotspots, and code smells reported by SonarCloud.
Configuration Description
Conditions (all must be true):
extractSonarFindings
filter functionAutomation Actions:
Label SonarCloud Quality Reports
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\n{% for item in reports %}\nlabel_sonar_{{ item.name }}:\nif:\n- {{ item.count > 0}}\nrun:\n- action: add-label@v1\nargs:\nlabel: '{{ item.icon }} sonar:{{ item.name }}-{{ item.rating }}'\ncolor: {{ colors.red if (item.rating == 'E' or item.rating == 'D') else (colors.orange if (item.rating == 'C' ) else colors.yellow) }}\n{% endfor %}\nsonar: {{ pr | extractSonarFindings }}\nreports:\n- name: vulnerabilities\ncount: {{ sonar.vulnerabilities.count }}\nicon: \ud83d\udd13\nrating: {{ sonar.vulnerabilities.rating }}\n- name: code smells\ncount: {{ sonar.code_smells.count }}\nicon: \u2623\ufe0f\nrating: {{ sonar.code_smells.rating }}\n- name: security hotspots\ncount: {{ sonar.security_hotspots.count }}\nicon: \ud83d\udee1\ufe0f\nrating: {{ sonar.security_hotspots.rating }}\n- name: bugs\ncount: {{ sonar.bugs.count }}\nicon: \ud83e\udeb2\nrating: {{ sonar.bugs.rating }}\ncolors:\nred: 'b60205'\norange: 'd93f0b'\nyellow: 'fbca04'\n
Download this example as a CM file. "},{"location":"integrations/sonar/#review-sonar-duplications","title":"Review Sonar Duplications","text":"Request changes when Sonar reports an excessive level of duplicated code.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Sonar Duplications
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_sonar_duplications:\nif:\n- {{ sonar.duplications > 3 }}\nrun: - action: add-label@v1\nargs:\nlabel: 'Sonar: {{ sonar.duplications}}% duplication'\ncolor: {{ colors.yellow }}\n- action: request-changes@v1\nargs:\ncomment: |\nSonar reports an excessive level of code duplication. Please consider refactoring your PR to reduce duplications.\nsonar: {{ pr | extractSonarFindings }}\ncolors:\nyellow: 'fbca04'\n
Download this example as a CM file. "},{"location":"integrations/sonar/#review-sonar-security-alerts","title":"Review Sonar Security Alerts","text":"Require additional reviews for Sonar security alerts. gitStream will remove this requirement if the alerts are resolved.
Configuration Description
Conditions (all must be true):
Automation Actions:
my-organization/security-team
team. Customize this to match your organization.Review Sonar Alerts
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_sonar_alerts:\nif:\n- {{ sonar.code_smells.rating != 'A' or sonar.vulnerabilities.rating != 'A' or sonar.security_hotspots.rating != 'A'}}\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [my-organization/security-team]\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR requires additional review because it fails to meet SonarCloud clean code standards.\nsonar: {{ pr | extractSonarFindings }}\n
Download this example as a CM file."},{"location":"integrations/swimm/","title":"Integrate gitStream with Swimm","text":""},{"location":"integrations/swimm/#approve-swimm-changes","title":"Approve Swimm Changes","text":"Approve changes that only affect Swimm documentation.
Configuration Description
Conditions (all must be true):
.swm
extension.Automation Actions:
swimm-docs-only
labelApprove Swimm Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\napprove_swimm_changes:\n# Triggered for any changes to Swimm documentation\nif:\n- {{ branch.diff.files_metadata | match(attr='file', regex=r/\\.swm\\//) | every }}\n# Apply a swimm-docs-only label, approve the PR and explain why in a comment.\nrun: - action: add-label@v1\nargs:\nlabel: 'swimm-docs-only'\n- action: approve@v1\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR is considered a safe change as it only affects Swimm Docs. \nIt has been automatically approved.\n
Download this example as a CM file. Special thanks to Omerr for providing this example.
"},{"location":"integrations/terraform/","title":"Integrate gitStream with Terraform","text":"Terraform Examples:
Assign Reviewers for Terraform Changes
Review New Terraform Module
Review Terraform Source Version
Review Terraform Module Name
Automatically assign org/infrastructure
team for reviewing changes when PR contains Terraform file changes.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_terraform:\n# Triggered for any changes to Terraform files\nif:\n- {{ files | match(regex=r/.*\\.tf.*/) | some }}\n# Assign infrastructure team as reviewer for change in Terraform files\nrun:\n- action: require-reviewers@v1\nargs:\nreviewers: [org/infrastructure]\n- action: add-comment@v1\nargs:\ncomment: |\nThis PR affects Terraform configurations and requires a review from the Infra team.\n
Download this example as a CM file. "},{"location":"integrations/terraform/#enforce-requirements-for-new-terraform-modules","title":"Enforce Requirements for New Terraform Modules","text":"Request changes if a PR that creates a new Terraform module which do not conform to the required directory structure.
Configuration Description
Conditions (all must be true):
/modules
directory.Automation Actions:
\u26a0\ufe0f Missing Terraform Components
Review New Module
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n{% set misslist = [] %}\n{% for pattern in terraform %}\n{% if (newfilesinpr | match(term=pattern) | nope) %}\n{% set misslist = misslist + [pattern+' '] %}\n{% endif %}\n{% endfor %} automations:\nreview_new_terraform_module:\nif: - {{misslist | match(regex=r/.*/) | some}}\n- {{is.mainfile and is.mainfilenotinroot }}\nrun:\n- action: add-comment@v1\nargs:\ncomment: |\nNew terraform modules must contain all required components before merging. Please update your PR with the required components and gitStream will automatically remove this comment once completed.\nHere are the required components, {{misslist}} should be customized appropriately:\nmy_module/\n\u251c\u2500\u2500 main.tf\n\u251c\u2500\u2500 outputs.tf\n\u251c\u2500\u2500 providers.tf\n- action: add-label@v1\nargs:\nlabel: '\u26a0\ufe0f Missing Terraform Components'\ncolor: '#FFA500'\nresources:\nmodule_directory: 'modules'\nterraform:\n- main.tf\n- outputs.tf\n- providers.tf\nis:\nmainfile: {{newfilesinpr | match(term = \"main.tf\") | some}}\nmainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = \"main.tf\") | nope }}\nnewfilesinpr:\n{{ branch.diff.files_metadata | map(attr='new_file')}}\n
Download this example as a CM file. "},{"location":"integrations/terraform/#ensure-terraform-source-urls-have-version-numbers","title":"Ensure Terraform Source URLs have version numbers","text":"Ensure that all Terraform modules imported via a source URL specify a version.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Changes
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\nautomations:\nreview_terraform_source_version:\n# Check if New Content contains a source URL, the URL is not part of allow list and lacks version reference\nif: - {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\\\".*(http|https).*\\\"/) | some }}\n- {{ source.diff.files | match(attr='new_content', list=allowlist) | nope }}\n- {{ source.diff.files | match(attr='new_content', regex=r/source.*?=.*\\?ref=v.*/) | nope }}\nrun:\n- action: request-changes@v1\nargs:\ncomment: |\nYou must reference a specific version when accessing Terraform module sources via URL, e.g. `?ref=v1.0.0`. Please update your Terraform files to follow this practice.\nallowlist:\n- 'https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git'\n- 'https://github.com/terraform-aws-modules/terraform-aws-vpc.git'\n- 'https://github.com/terraform-aws-modules/terraform-aws-eks.git'\n
Download this example as a CM file. "},{"location":"integrations/terraform/#ensure-new-terraform-modules-conform-to-a-naming-pattern","title":"Ensure New Terraform Modules conform to a Naming Pattern","text":"Request changes if a PR creates a new Terraform module that is missing a required prefix or keyword in the name.
Configuration Description
Conditions (all must be true):
Automation Actions:
Review Terraform Module Name
# -*- mode: yaml -*-\nmanifest:\nversion: 1.0\n# Prefix Check Logic\n{% set prefixcheck = [] %}\n{% for pattern in terraform.prefixes %}\n{% if(newfilesinpr | match(term=module_location + pattern) | some) %}\n{% set prefixcheck = prefixcheck + [true]%}\n{% else %}\n{% set prefixcheck = prefixcheck + [false] %}\n{% endif %}\n{% endfor %}\nautomations:\nreview_new_terraform_module:\nif: - {{is.mainfile and is.mainfilenotinroot}}\n- {{module_name_checks.prefix or module_name_checks.keyword}}\nrun:\n- action: request-changes@v1\nargs:\ncomment: |\nTerraform module names must contain a required prefix and keyword:\n* Prefixes: {{ terraform.prefixes }}\n* Keywords: {{ terraform.keywords }}\nmodule_name_checks:\nprefix: {{prefixcheck | match(term='true') | nope}}\nkeyword: {{newfilesinpr | match(list=terraform.keywords) | nope}}\nmodule_location: infrastructure/modules/\nterraform:\nprefixes: ['aws', 'gcp', 'azure']\nkeywords: ['db', 'networking', 'security']\nis:\nmainfile: {{newfilesinpr | match(term = \"main.tf\") | some}}\nmainfilenotinroot: {{source.diff.files | map(attr='original_file') | match(term = \"main.tf\") | nope }}\nnewfilesinpr:\n{{ branch.diff.files_metadata | map(attr='new_file')}}\n
Download this example as a CM file."},{"location":"integrations/golang/golang-testing-automations/","title":"Golang Testing Automations","text":""},{"location":"integrations/golang/golang-testing-automations/#review-missing-golang-tests","title":"Review Missing Golang Tests","text":""},{"location":"integrations/golang/golang-testing-automations/#review-python-golang-test-name","title":"Review Python Golang Test Name","text":"Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/html/html-css-automations/","title":"HTML/CSS Automations","text":""},{"location":"integrations/html/html-css-automations/#flag-missing-html-tags","title":"Flag Missing HTML Tags","text":""},{"location":"integrations/html/html-css-automations/#flag-duplicate-h1","title":"Flag Duplicate H1","text":""},{"location":"integrations/html/html-css-automations/#enforce-html-title-length-requirements","title":"Enforce HTML Title Length Requirements","text":""},{"location":"integrations/html/html-css-automations/#enforce-image-alt-attributes","title":"Enforce Image Alt Attributes","text":"Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/java/java-testing-automations/","title":"Java Testing Automations","text":""},{"location":"integrations/java/java-testing-automations/#review-missing-java-tests","title":"Review Missing Java Tests","text":""},{"location":"integrations/java/java-testing-automations/#review-python-java-test-name","title":"Review Python Java Test Name","text":"Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/javascript/javascript-testing-automations/","title":"JavaScript Testing Automations","text":""},{"location":"integrations/javascript/javascript-testing-automations/#review-missing-javascript-tests","title":"Review Missing JavaScript Tests","text":""},{"location":"integrations/javascript/javascript-testing-automations/#review-python-javascript-test-name","title":"Review Python JavaScript Test Name","text":"Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/python/python-testing-automations/","title":"Python Testing Automations","text":""},{"location":"integrations/python/python-testing-automations/#review-missing-python-tests","title":"Review Missing Python Tests","text":""},{"location":"integrations/python/python-testing-automations/#review-python-test-name","title":"Review Python Test Name","text":"Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"integrations/ruby/ruby-testing-automations/","title":"Ruby Testing Automations","text":""},{"location":"integrations/ruby/ruby-testing-automations/#review-missing-ruby-tests","title":"Review Missing Ruby Tests","text":""},{"location":"integrations/ruby/ruby-testing-automations/#review-python-ruby-test-name","title":"Review Python Ruby Test Name","text":"Special thanks to Boemo W Mmopelwa for providing these examples.
"},{"location":"snippets/automation-footer/","title":"Automation footer","text":"More Automations can be found on the Automation Library and Integrations pages.
"},{"location":"snippets/change-request-automation/","title":"Change request automation","text":"gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.
Learn More about how gitStream Works.
"},{"location":"snippets/javascript-automation/","title":"Javascript automation","text":"More Automations can be found on the Automation Library and Integrations pages.
Check that you see gitStream app on repository's Settings > GitHub apps:
In case you don't see it, visit the marketplace and install it for free: https://github.com/marketplace/gitstream-by-linearb
Check you have placed these two files in your repository with these exact names:
gitstream.cm
in the cm
repo, (for org level installs), or .cm/gitstream.cm
on all other repositories.github/workflows/gitstream.yml
These files must be committed to the repository default branch (usually master
or main
). Notice that the action will not run until these files are found on the default branch.
Check that you see "gitStream workflow automation" in the Action section in your repository:
Next, if you see failed action, check out the details:
Some organization limit which actions can run, in that case in the repository settings you should enable it:
Also, add
to the Allow specified actions and reusable workflows list, if it is shown.cm
repoMake sure you have added the cm
repo to the repos gitStream should run on
gitStream automations won't trigger for PRs that are in Draft mode.
This error indicates that gitStream is unable to locate the file .github/workflows/gitstream.yml
. The tool first searches for this file in the cm
repository and then in the PR's repository. If the CI file is not found, this error message is displayed. To resolve this issue, ensure that your setup is correct and that the specified file exists in your repository.
For example, when using the set-required-approvals
action, gitStream can ensure the PR got enough approvals before it can be merged. gitStream does that by running as a check and marking the check conclusion as failed. In order for the PR to be blocked, gitStream should be set as a required check in the repo: instructions here.
In order for gitStream to be listed as a required check, it needs to be triggered at least once in that repo. First create a new PR so gitStream is triggered.
Check it under repository's Settings > Branches:
You can edit the .github/workflows/gitstream.yml
and uncomment the if
line, you can edit and replace the bot name with the bot name you want to ignore (dependabot[bot]
in the example below):
jobs:
+ gitStream:
+ timeout-minutes: 5
+ # uncomment this condition, if you don't want any automation on dependabot PRs
+ if: github.actor != 'dependabot[bot]'
+ runs-on: ubuntu-latest
+ name: gitStream workflow automation
+ steps:
+ - name: Evaluate Rules
+ uses: linear-b/gitstream-github-action@v1
+
gitStream check run can fail from different reasons, and these are shown in the check result.
When it says gitStream.cm Skipped — gitStream workflow file not found
, it means that the GitHub action was not found, check again that you have this file in your repository root: .github/workflows/gitstream.yml
, see instructions on GitHub installation.
Clicking the Details
button will show more information and context.
You can add this automation to see details on context variable.
You can dump any context value to the PR comment. For example, to see the list of changed files, use:
automations:
+ show_changed_files:
+ if:
+ - true
+ run:
+ - action: add-comment@v1
+ args:
+ comment: |
+ FILES DUMP {{ files | dump | safe }}
+ JS FILES DUMP {{ files | filter(regex=r/\.js$/) | dump | safe }}
+
IntelliJ IDEA has automatic code styling for YAML that can break the .cm
syntax, check the following Settings/Preferences | Editor | Code Style | YAML --> Spaces | Code braces and make sure it is unchecked.
VS Code YAML plugin by Red Hat extension [vscode-yaml](https://github.com/redhat-developer/vscode-yaml)
has automatic code styling for YAML that can break the .cm
syntax, make sure you disable bracketSpacing
Create a new issue in the project's issues