Automation actions

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

Legend

The icons indicate the availability status of each action.

Supported on GitHub
Supported on GitLab
Open beta - Feature is under development and currently available for all

Overview

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

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

example

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

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	[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 have passed

example

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

example

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.

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

`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

example

automations:
  slack_message:
    if:
      - true
    run:
      - action: send-http-request@v1
        args:
          url: "{{ slack.base }}/{{ env.SLACK_WEBHOOK }}"
          method: POST
          headers: '{"Content-type": "application/json", "Authorization": "Bearer {{env.secrets.slack}}}'
          body: '{"text": "Hello, world!"}'
slack:
   base: "https://hooks.slack.com/services"
   channel: {{ 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

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

example

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

example

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

This action will invoke the run of a workflow dispatch; thus, it might result in significant GitHub action minutes charge.
We encourage you to use this action with custom triggers