Skip to content

Automation actions

Actions are the end results of the automation described in your .cm file.

Note

Items marked with are under development and are not available yet.

Overview

gitStream executes actions in the order they are listed. If an action result fails, following actions will not be executed.

Note

Multiple actions can be listed in a single automation. The actions are invoked one by one.

Dynamic actions arguments

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"

Reference

add-comment

This action, once triggered, adds a comment to the PR.

Args Usage Type Description
comment Required String Sets the comment, markdown is supported
example
automations:
  senior_review:
    if:
      - {{ files | match(term='core/') | some }}
    run:
      - action: add-comment@v1
        args:
          comment: |
            Core service update
            (Updates API)

add-label

This action, once triggered, adds a label 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
label Required String The label text any string can work
color Optional String The color in hexa, for exmaple: 'FEFEFE' (you can also add # prefix #FEFEFE)
example
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 or team_reviewers [String] Sets reviewers user name
team_reviewers Required or reviewers [String] Sets reviewers teams name, without the @ prefix
example
automations:
  senior_review:
    if:
      - {{ files | match(term='src/ui/') }}
    run:
      - action: add-reviewers@v1
        args:
          reviewers: [popeye, olive]

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.

example
automations:
  small_change:
    if:
      - {{ source.diff.files | isFormattingChange }}
    run:
      - action: approve@v1

close

This action, once triggered, close the PR without merging.

example
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 set to wait for required checks to pass or ignore checks.

Args Usage Type Description
wait_for_all_checks Optional Boolean By default false, so only Required checks can block merge, when true the action won't merrge even if non-Required check fail
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
example
automations:
  small_change:
    if:
      - {{ files | allDocs }}
    run:
      - action: merge@v1
        args:
          rebase_on_merge: true

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.

Note

You should enable branch protection, so GitHub will prevent merging unless the gitStream action check pass successfully.

Args Usage Type Description
approvals Required Integer Sets the number of required reviewer approvals for merge for that PR
example
automations:
  double_review:
    if:
      - {{ files | match(regex=r/agent\//) | some }}
    run:
      - action: set-required-approvals@v1
        args:
          approvals: 2

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
example
automations:
  catch_deprecated:
    if:
      - {{ source.diff.files | matchDiffLines(regex=r/^[+].*oldFetch\(/') | some }}
    run:
      - action: request-changes@v1
        args:
          comment: |
            You have used deprected API `oldFetch`, use `newFetch` instead.

require-reviewers

This action, once triggered, requires a specific reviewer approval.

Args Usage Type Description
reviewers Required [String] Sets reviewers user name, merge is blocked till approved by any of the listed users
also_assign Optional Bool true by default, also assign the specified users as reviewers
example
automations:
  senior_review:
    if:
      - {{ files | match(regex=r/src\/ui\//) | some }}
    run:
      - action: require-reviewers@v1
        args:
          reviewers: ['popeye', 'olive']