Examples
Here are some examples of actions that can be applied on repositories by gitStream.
Tip
See full list on the gitStream repository.
Review Efficiency
Label PRs by complexity
Automatically add a color-coded label to PRs with the estimated review time.
When used, each PR will be annotated with this label. When there are new commits to the PR, gitStream manage the label and replace it with an updated review time when needed.
automations:
estimated_time_to_review:
if:
- true
run:
- action: add-label@v1
args:
label: "{{ calc.etr }} min review"
color: {{ 'E94637' if (calc.etr >= 20) else ('FBBD10' if (calc.etr >= 5) else '36A853') }}
# To simplify the automation, this calculation is placed under a unique YAML key.
# The result is assigned to `calc.etr` which is used in the automation above.
# You can add as many keys as you like.
calc:
etr: {{ branch | estimatedReviewTime }}
Approve safe changes
PRs that include only documentation changes are verified and approved by gitStream. In the example below, marked in yellow, the files context is checked by allDocs filter that verifies there are only document files. PRs that pass the check are approved by gitStream.
Check out the functions to learn more:
automations:
safe_changes:
if:
- {{ is.formatting or is.docs or is.tests or is.asset }}
run:
- action: add-label@v1
args:
label: 'safe-changes'
- action: approve@v1
# To simplify the automation, this calculation is placed under a unique YAML key.
# The result is is assigned to `is.formatting`, `is.docs` and `is.tests` which is
# used in the automation above. You can add as many keys as you like.
is:
formatting: {{ source.diff.files | isFormattingChange }}
docs: {{ files | allDocs }}
tests: {{ files | allTests }}
asset: {{ files | match(regex=r/\.(png|svg|gif|css)$/) | every }}
Review Quality
Like CODEOWNERS but better
With gitStream you can define your sensitive areas, set reviewers, while allowing faster merge time for non-sensitive changes.
The nope filter is used to make sure no change is in a sensitive file.
Tip
You can also use regex instead of normal strings, see here
automations:
approve_non_sensitive:
if:
- {{ files | match(list=sensitive) | nope }}
run:
- action: add-label@v1
args:
label: 'non-sensitive'
color: '#2CA44E'
- action: approve@v1
require_review:
if:
- {{ files | match(list=sensitive) | some }}
run:
- action: add-reviewers@v1
args:
team_reviewers: ['a-team']
- action: set-required-approvals@v1
args:
approvals: 1
sensitive:
- src/app/auth/
- src/app/routing/
- src/app/resources/
Review PRs with Code Experts
Not every review is equal, getting the right one is important to get high quality feedback.
Overall, selecting the right reviewer for your pull request 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. The codeExperts filter (learn more here) can help simplify this process by highlighting the most qualified contributors based on their activity in the relevant code area.
automations:
code_experts:
if:
- true
run:
- action: add-reviewers@v1
args:
reviewers: {{ repo | codeExperts(gt=10) }}
- action: add-comment@v1
args:
comment: |
{{ repo | explainCodeExperts(gt=10) }}
Using explainCodeExperts shows the resulting data in the PR comment.
Last, the codeExperts assigns the code experts to review the PR automatically.
You can read more on both in the function filter page.
Mark PRs without tests
PRs that don't have tests changes can be marked automatically.
When a PR is opened without any tests, this label is added:
Once the tests are added and committed, gitStream automatically removes the label:
automations:
no_tests:
if:
- {{ files | match(regex=r/(test|spec)/) | nope }}
run:
- action: add-label@v1
args:
label: 'missing-tests'
color: '#E94637'
Require 2 approvals for complex PRs
Automatically require 2 reviewers for PRs that have more than 100 lines of code changed under the src directory.
This ability can be very useful if you want to have more approvals for certain PRs, but rather than increasing the required approvals for all PRs using GitHub repo settings, it allows doing that only for specific PRs.
Multiple conditions in the if section has AND relationship and must all be true for the automation to execute.
automations:
double_review:
if:
- {{ branch | estimatedReviewTime >= 30 }}
- {{ files | length >= 10 }}
- {{ files | match(regex=r/src\//) | some }}
run:
- action: set-required-approvals@v1
args:
approvals: 2
Note
gitStream should be set as required check in the repo so it can block merge
Share knowledge
When setting lt to 50, which stands for the less-than sign: <, only those who contributed less than 50% of lines overall are selected. Applying random will pick one from the list.
automations:
share_knowledge:
if:
- true
run:
- action: add-reviewers@v1
args:
reviewers: {{ repo | rankByGitBlame(lt=50) | random }}
Mark PRs with deleted files
When files are removed entirely you want to be sure it is not by accident, mark these PRs.
automations:
deleted:
if:
- {{ has.deleted_files }}
run:
- action: add-label@v1
args:
label: 'deleted-files'
color: '#DF9C04'
has:
deleted_files: {{ source.diff.files | map(attr='new_file') | match(term='/dev/null') | some }}
Review Policy
Close PRs when touching out-of-scope files
This action, once triggered, close the PR without merging.
You can also replace close with requested-changes to leave the PR open but request to undo the UI changes.
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
Assign mentors to new contributors
During the first 21 days, a contributor is assigned automatically to get reviews by specific people. By changing 21 you can add or reduce the amount of time.
Make sure to change the reviewers according to your team members.
automations:
junior:
if:
- {{ repo.author_age < 21 and (repo.age - repo.author_age) >= 21 }}
run:
- action: add-label@v1
args:
label: 'first-weeks'
color: '#FBBD10'
- action : add-comment@v1
args:
comment: |
During your first 21 days, your team lead will be assigned to review your PRs.
- action: add-reviewers@v1
args:
reviewers: [popeye]
Validate new component has required field
You can define required fields for components, so when your team members adds new components they should also add the required field, description in the example below.
automations:
catch_deprecated_components:
if:
- {{ source.diff.files | matchDiffLines(regex=r/LambdaFunction/) | some }}
- {{ source.diff.files | matchDiffLines(regex=r/description:/) | nope }}
run:
- action: add-label@v1
args:
label: 'lambda-missing-field'
color: '#FF0000'
- action: request-changes@v1
args:
comment: |
New `LambdaFunction` must have `description:` field.
Request changes on deprecated APIs
For example, assume we have an old API callElvis we want to switch from to a new API callGaga, gitStream can review and trigger a change request automatically when the PR includes use of the deprecated API.
This pattern allows defining best practices in .cm code.
automations:
catch_deprecated_components:
if:
- {{ source.diff.files | matchDiffLines(regex=r/callElvis/) | some }}
run:
- action: add-label@v1
args:
label: 'deprecated-component'
color: '#FF0000'
- action: request-changes@v1
args:
comment: |
you have used deprecated API, use `callingGaga` instead
gitStream supports iterators over arrays and dictionaries, so you can also make it more general:
automations:
{% for item in deprecated %}
# Automation names should be unique, therefore the iteration number postfix
catch_deprecated_components_{{ loop.index }}:
if:
- {{ source.diff.files | matchDiffLines(regex=item.regex) | some }}
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 %}
# This list includes the deprecated items
deprecated:
- regex: r/callElvis/
old: Elvis
new: Gaga
- regex: r/callOldAPI/
old: callOldAPI
new: callBetterAPI
More examples
More examples can be found in the gitStream repository.
Tip
You can boost your GitHub reputation with your new automation rule - open a PR and add it to the gitStream repository