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.

add-comment
add-label
add-labels
add-reviewers
approve
close
merge
set-required-approvals
require-reviewers
request-changes

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.

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

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, 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`)

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
`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

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 merge 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.

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

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

example

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.

Args	Usage	Type	Description
`reviewers`	Required	[String]	Sets reviewers user name, merge is blocked till approved by either of the listed users
`team_reviewers`	Required or `reviewers`	[String]	Sets reviewers teams name, without the `@` prefix
`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']

Attention

To allow this action to block merge, you should enable branch protection, and gitStream has to be set as required check in GitHub.