Actions | Elevatic Documentation

🔰 fundamental topics for beginners getting started with DevSensei
🔬 advanced topics for once you have your first workflows automated

List of available actions that fuel your automation.

`add-reviewers` action since 8.8

Suggests and/or adds reviewers to a pull request. (See also add-watchers for watchers instead)

Action option	Definition
`members`	Decides which users are selected to be added as reviewers. Choice 1: `codeowners` requires Code Owners custom attribute to be defined. Members will be resolved according to the rules applied to the overall diff of the PR. YAML `- add-reviewers: members: codeowners` Choice 2: identifier list Identifiers are either a user slug, an email address or a group reference (either to a custom group, or to a Bitbucket group). Group references are resolved transitively to all members of the group. YAML `- add-reviewers: members: - user1 # user slug - user2@domain.com # email address - @@my-group # group reference`
`assignment-limit` (optional)	number limit the number of reviewers that can be assigned to a pull request. This feature is useful to prevent unwanted notifications in the case of manipulation mistakes (e.g., creating a Pull Request from the wrong branch, or an unhappy rebase) YAML `- add-reviewers: assignment-limit: 20`
`assignment-routing` (optional)	`random: n` (where `n` is a positive integer) reduce the number of reviewers that are automatically assigned to a pull request. Currently, the only available method of assignment is at random. YAML `- add-reviewers: assignment-routing: random: 2`
`strategy` (optional)	choice from `assign-only`, `suggest-only`, or `suggest-and-assign` (default). Suggested reviewers are automatically applied to the `Reviewers` input field on the Create Pull Request page. Assigned reviewers are added as reviewers whenever the action is triggered. YAML `- add-reviewers: strategy: suggest-only`

`add-watchers` action since 8.8

Adds watchers to a pull request. (See also add-reviewers for reviewers instead)

Action option	Definition
`members`	Decides which users are selected to be added as watchers. Choice 1: `codeowners` requires Code Owners custom attribute to be defined. Members will be resolved according to the rules applied to the overall diff of the PR. YAML `- add-watchers: members: codeowners` Choice 2: identifier list Identifiers are either a user slug, an email address or a group reference (either to a custom group, or to a Bitbucket group). Group references are resolved transitively to all members of the group. YAML `- add-watchers: members: - user1 # user slug - user2@domain.com # email address - @@my-group # group reference`

Action option

Definition

members

Decides which users are selected to be added as watchers.

Choice 1: codeowners

requires Code Owners custom attribute to be defined. Members will be resolved according to the rules applied to the overall diff of the PR.

YAML

- add-watchers:
    members: codeowners

Choice 2: identifier list

Identifiers are either a user slug, an email address or a group reference (either to a custom group, or to a Bitbucket group).

Group references are resolved transitively to all members of the group.

YAML

- add-watchers:
    members:
      - user1            # user slug
      - user2@domain.com # email address
      - @@my-group       # group reference

`unapprove` action since 8.5

Unapprove all or some of the approved reviews in the Pull Request.

Action option	Definition
`members`	Decides which users are selected to be unapproved. Choice 1: `all` unapprove all users who are currently reviewers. YAML `- unapprove: members: all` Choice 2: `codeowners` requires Code Owners custom attribute to be defined. Members will be resolved according to the rules applied to the diff of the most recent change to the PR. YAML `- unapprove: members: codeowners` Choice 3: identifier list Identifiers are either a user slug, an email address or a group reference (either to a custom group, or to a Bitbucket group). Group references are resolved transitively to all members of the group. YAML `- unapprove: members: - user1 # user slug - user2@domain.com # email address - @@my-group # group reference`

Action option

Definition

members

Decides which users are selected to be unapproved.

Choice 1: all

unapprove all users who are currently reviewers.

YAML

- unapprove:
    members: all

Choice 2: codeowners

requires Code Owners custom attribute to be defined. Members will be resolved according to the rules applied to the diff of the most recent change to the PR.

YAML

- unapprove:
    members: codeowners

Choice 3: identifier list

Identifiers are either a user slug, an email address or a group reference (either to a custom group, or to a Bitbucket group).

Group references are resolved transitively to all members of the group.

YAML

- unapprove:
    members:
      - user1            # user slug
      - user2@domain.com # email address
      - @@my-group       # group reference

`add-comment` action since 8.2

Adds a single comment or task to a pull request. Can either be custom content, or automated reporting of action results.

See also the add-checklist action below for more flexibility

Action option	Definition
`content` (exclusive)	(`string`) templated content of the comment, may contain template splices. YAML `add-comment: content: 'Warning! too many commits: found ${count(commits)}'`
`report-from` (exclusive)	(`string`) key referring to a previous action result in the workflow. YAML `add-comment: report-from: add-reviewers` DevSensei will use a builtin formatter to report the results of the action in a readable format. For now: 💡only `add-reviewers` is supported.
`task`	(`boolean`) whether create as a task (defaults to false) YAML `add-comment: content: \| This PR is missing a Jira issue key in the title. Please add it. task: true`

Action option

Definition

content (exclusive)

(string) templated content of the comment, may contain template splices.

YAML

add-comment:
  content: 'Warning! too many commits: found ${count(commits)}'

report-from (exclusive)

(string) key referring to a previous action result in the workflow.

YAML

add-comment:
  report-from: add-reviewers

DevSensei will use a builtin formatter to report the results of the action in a readable format.

For now: 💡only add-reviewers is supported.

task

(boolean) whether create as a task (defaults to false)

YAML

add-comment:
  content: |
    This PR is missing a Jira issue key in the title.
    Please add it.
  task: true

`add-checklist` action since 9.1.0

Adds a complete checklist of tasks and comments to a pull-request.

Action option	Definition
`title` (optional)	(`string`) title for the checklist, may contain template splices. Checklist items (see below) will be added as comment response to the title. YAML `add-checklist: title: Security checks`
`items`	(`array of items`) list of items for your checklist An item can be a Comment or a Task. Comment: a `string` with the content, may contain template splices Task: a mapping `task: <string>` where the string is the content of your task, may contain template splices YAML `add-checklist: items: - task: "Bump version number" - "Release is done!"`
`duplicate-strategy` (optional)	(`enum`) describes what behaviour to have when the checklist is re-added when action re-run Options are: `keep-existing` (default): the existing checklist is kept as is (with all responses/checked tasks) and no new checklist is created `create-new`: same as `keep-existing`, except a duplicate checklist will be created `reset-existing`: same as `keep-existing`, except previously checked task items will be unchecked YAML `add-checklist: items: - ... duplicate-strategy: create-new`

Action option

Definition

title (optional)

(string) title for the checklist, may contain template splices. Checklist items (see below) will be added as comment response to the title.

YAML

add-checklist:
  title: Security checks

items

(array of items) list of items for your checklist

An item can be a Comment or a Task.

Comment: a string with the content, may contain template splices
Task: a mapping task: <string> where the string is the content of your task, may contain template splices

YAML

add-checklist:
  items:
  - task: "Bump version number"
  - "Release is done!"

duplicate-strategy (optional)

(enum) describes what behaviour to have when the checklist is re-added when action re-run

Options are:

keep-existing (default): the existing checklist is kept as is (with all responses/checked tasks) and no new checklist is created
create-new: same as keep-existing, except a duplicate checklist will be created
reset-existing: same as keep-existing, except previously checked task items will be unchecked

YAML

add-checklist:
  items:
  - ...
  duplicate-strategy: create-new

`decline` action since 8.11

Declines the pull request, adding a comment for justification.

Action option	Definition
`comment`	Required, specifies the reason for declining the pull request. It may contain template splices.

Use case

This action can be used together with the Age attribute to automatically decline old pull requests.

YAML

workflows:
  - name: Declines old pull requests
    conditions:
      - age > duration('7 days')
    actions:
      - decline:
          comment: Declined because it stayed open for one week.

`suggest-description` action since 8.11

Suggests a pull request title and/or description on the Create Pull Request page.

This action does not modify an existing pull request. It only provides suggestions to the user when creating a pull request.

Action option	Definition
`title` (optional)	(`string`) suggested pull request title. The value supports templating with `${…}` (see String Template Literals). YAML `- suggest-description: title: "PR: ${source} -> ${destination}"`
`description` (optional)	(`string`) suggested pull request description. The value supports templating with `${…}` (see String Template Literals). YAML `- suggest-description: description: \| ## Commits - ${join(commits.titles, '\n- ')} ## Jira Issues ${join(jira-keys, " ")}`

At least one of title or description must be configured.

`autofill-placeholders` action since 8.11

Automatically expands ${…} placeholders in the pull request title and/or description.

Typical use case: you create pull requests via REST API, or users want to write a custom expression in the description. DevSensei will replace these placeholders with their concrete values.

Action option	Definition
`strategy` (optional)	(`string`) when to autofill placeholders. If no strategy is configured then `on-update` is selected. YAML `- autofill-placeholders: strategy: on-update`

`strategy` option	Definition
`on-update` (default)	When actions are triggered, update the pull request if valid placeholders are present in the title/description. 💡 Configure `retrigger-on` for `title` and/or `description` so placeholders are re-expanded whenever the user edits the pull request title/description. YAML `workflows: - name: Autofill placeholders retrigger-on: - title - description actions: - autofill-placeholders:`

strategy option

Definition

on-update (default)

When actions are triggered, update the pull request if valid placeholders are present in the title/description.

💡 Configure retrigger-on for title and/or description so placeholders are re-expanded whenever the user edits the pull request title/description.

YAML

workflows:
  - name: Autofill placeholders
    retrigger-on:
      - title
      - description
    actions:
      - autofill-placeholders:

`schedule-auto-merge` action since 8.3

Schedules this pull request to be automatically merged once all merge checks are clear.

schedule-auto-merge shares some functionality with the Auto Merge DevSensei feature, however the features operate independently.

If your repository uses branch permissions to prevent all changes on a branch, then the schedule-auto-merge action will only work with the merge-as-author: true flag.

Action option	Definition
`strategy`	Optional, possible values: `ff`, `ff-only`, `no-ff`, `rebase-ff-only`, `rebase-no-ff`, `squash`, `squash-ff-only` Merge strategy used for the pull request. When not specified, the default merge strategy of the repository will be used. Strategy must be allowed by the repository configuration. YAML `schedule-auto-merge: strategy: squash`
`message`	Optional (`string`) templated message for the merge commit, may contain template splices. YAML `schedule-auto-merge: strategy: no-ff message: \| Merged PR ${title} by DevSensei policy ${description}`
`merge-as-author`	Optional (`boolean`). By default, DevSensei will automatically merge Pull Requests using its own service account. To merge on behalf of the Pull Request author, set `merge-as-author` to true. YAML `schedule-auto-merge: merge-as-author: true`
`merge-as`	Optional (`string`). By default, DevSensei will automatically merge Pull Requests using its own service account. To configure a custom user, set `merge-as` to the username or email of the desired user. This user must have write access to the repository. YAML `schedule-auto-merge: #merge-as: username #merge-as: @"Complex Name" merge-as: user@domain.com`
`auto-subject`	Optional (`boolean`). When true, Bitbucket generates a message summarizing the merge. If no `message` is specified, this is always true.

Prerequisites

This action requires:

Bitbucket 8.15 or newer
The Bitbucket Auto-Merge feature must be enabled for the repository

Auto-Merge Behavior

When the action runs, it submits an Auto-Merge for this pull request. Bitbucket then will merge the pull request, depending on its state:

Pull Request State	What Bitbucket Does
Pull request is mergeable	Immediately merges it
Merge checks are failing	Merges as soon as merge checks pass
Merge conflict is present	No Auto Merge Request is submitted
A commit changes/new commits added while pull request is open	Auto Merge status is cancelled, and DevSensei will not re-submit a Auto Merge Request until the workflow is retriggered.

Check the Bitbucket documentation for more details on how auto merge behaves.

Because the Auto-Merge request may be cancelled by new commits, you may decide to ask again for auto-merging. See the Retrigger On section for more details

Auto-Merge Use Cases

The schedule-auto-merge action makes it simpler to automatically accept lower risk pull requests by merging quickly. As it is based on Bitbucket’s Auto Merge feature, after scheduling, Bitbucket will still prevent merge if there is a veto from one of the merge checks enabled for your repository (for example anything in the merge-checks section).

Use Case	Example Workflow
Fast track code based on a `source` branch prefix or suffix, e.g. hotfix, code formatting, or documentation fixes, bypassing other checks.	YAML `conditions: - source ~= 'hotfix/*' actions: - schedule-auto-merge: strategy: no-ff message: Hotfix branch ${source}`
Fast track code based if build succeed and is from a trusted bot-author, e.g. one that only submits library dependency updates.	YAML `conditions: - author = 'deps-updater-bot' - count(builds.successful) > 1 - count(builds.in-progress) = 0 - count(builds.failed) = 0 actions: - schedule-auto-merge: strategy: no-ff message: dependency updates`
Merge when the developer requests to skip reviewers, for example by adding a `title` with a specific prefix. You can also achieve this using the DevSensei Auto Merge feature, which has the benefit of an interactive graphical user interface, and when skipping is requested it automatically removes the "Codeowners minimum approvals" merge check. Alternatively, instead of checking the `title`, you could also look for a pattern in the `source` branch.	YAML `conditions: - title ~= '[SKIP]*' actions: - schedule-auto-merge: strategy: no-ff message: skipped reviewers`
Merge when a PR is without conflicts and not in a draft state.	YAML `conditions: - "!draft" - "!conflicts" actions: - schedule-auto-merge: strategy: no-ff message: no draft or conflict`
Merge when a required number of approvals is met (Equivalent to SHIP/SHOW/ASK).	YAML `conditions: - title ~= '[ASK>1]*' - count(approved-by) > 1 actions: - schedule-auto-merge: strategy: no-ff message: no draft or conflict`

Other Auto-Merge Use Cases (Planned)

The following ideas rely upon planned or otherwise unimplemented features. Contact support to let us know your use case.

Schedule merge when a no reviewer requested changes. (requires new attribute)
Wait until another PR has been merged (e.g. merge queue)
Check total size of change is within a small range (requires a new attribute).

`add-codeowners` action since 7.0 deprecated

This action is now deprecated and divided into several smaller, more regular, features. See actions add-reviewers and unapprove, and merge check codeowners-check.

Adds Code Owners as reviewers to a pull request.

Action option	Definition
`assignment-limit`	number limit the number of Code Owners that can be assigned to a pull request. (opt-in) This feature is useful to prevent unwanted notifications in the case of manipulation mistakes (e.g., creating a Pull Request from the wrong branch, or an unhappy rebase) YAML `- add-codeowners: assignment-limit: 20`
`assignment-routing`	`random`: n reduce the number of Code Owners that are automatically assigned to a pull request. (opt-in) Currently, the only available method of assignment is at random. YAML `- add-codeowners: assignment-routing: random: 2`
`rules`	The Code Owners rules and merge checks. For existing `CODEOWNERS` users, copy your owner rules and the merge checks to the `rules` section. Note: for sub-directory overrides, check "Not supported settings" section. YAML `- add-codeowners: rules: \| * @jordan jordan@example.com /backend/ @@backendies /frontend/ @@frontendies`
`custom-groups`	Define custom Code Owners groups. YAML `- add-codeowners: rules: \| pipelines.yml @@admins backend/ @@backendies src/components/*/.js @@frontendies custom-groups: admins: - @bobby backendies: - @jordan - john.doe@localhost.ch frontendies: - @charly - @@admins`
`auto-unapprove-on-change`	Remove approval if owned code changes. YAML `- add-codeowners: auto-unapprove-on-change: true`

`cancel-auto-merge` action (Planned)

Cancels any pending auto merge. This action is planned. Contact support to let us know your use case.

add-reviewers action since 8.8

add-watchers action since 8.8

unapprove action since 8.5

add-comment action since 8.2

add-checklist action since 9.1.0

decline action since 8.11

Use case

suggest-description action since 8.11

autofill-placeholders action since 8.11

schedule-auto-merge action since 8.3

Prerequisites

Auto-Merge Behavior

Auto-Merge Use Cases

Other Auto-Merge Use Cases (Planned)

add-codeowners action since 7.0 deprecated

cancel-auto-merge action (Planned)

`add-reviewers` action since 8.8

`add-watchers` action since 8.8

`unapprove` action since 8.5

`add-comment` action since 8.2

`add-checklist` action since 9.1.0

`decline` action since 8.11

`suggest-description` action since 8.11

`autofill-placeholders` action since 8.11

`schedule-auto-merge` action since 8.3

`add-codeowners` action since 7.0 deprecated

`cancel-auto-merge` action (Planned)