Action Filters

Action filters can be applied to actions to control whether or not they execute based on information about the workload. There are three types of action filters: inclusive, exclusive, and internal. Inclusive action filters indicate the action should be included from the action set if the filter resolves to true. Exclusive action filters indicate the action should be excluded from the action set if the filter resolves to true. Internal action filters determine whether an action should be included or excluded based on the context of it’s evaluation.

always_run

A boolean filter that indicates this action should be executed even if there was a failure in the action set. An example of a scenario where you’d want to use this setting is with the unlock_staging_area action. Even if your long-running local build process fails, you may still want to unlock the staging area to allow the next build to commence.

To avoid issues with the commit phase of the action set, this filter can only be used with post-commit actions.
Default
false
Type
Internal
Supports Composite Workloads
true
Supported Workload Types
  • All
Example
staging_areas:
 - local_hab_build:
      workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*

habitat_packages:
  - package_one

subscriptions:
  - workload: staged_workload_released:{{agent_id}}:local_hab_build:*
    actions:
      - built_in:trigger_habitat_package_build
      - unlock_staging_area:local_hab_build:
          always_run: true

ignore_labels

An array of Github labels that, when applied to a pull request, indicate that this action should be skipped.

Default
[]
Type
Exclusive
Supports Composite Workloads
false
Supported Workload Types
Example
merge_actions:
  - built_in:bump_version:
      ignore_labels:
        - "Version: Skip Bump"

ignore_commands

An array of trigger words that, when present in a pull request’s title or description, indicate that this merge action should be skipped when that pull request is merged.

Default
[]
Type
Exclusive
Supports Composite Workloads
false
Supported Workload Types
Example
merge_actions:
  - built_in:bump_version:
      ignore_commands:
        - skip version
        - version skip

ignore_team_members

Skip the action if the GitHub user that opened the Pull Request is a member of one of the listed teams. You must specify the team name in the form of org_slug/team_slug omitting the @.

Default
[]
Type
Exclusive
Supports Composite Workloads
false
Supported Workload Types
Example
subscriptions:
  # Do not post a welcome message if the user belongs to one of the specified teams
  - workload: pull_request_opened:{{agent_id}}:*
    actions:
      - post_github_comment:.expeditor/templates/pull_request.mustache:
          ignore_team_members:
            - inspec/owners
            - inspec/inspec-core-team

not_if

Do not trigger the action if any of the listed actions have triggered.

Default
[]
Type
Exclusive
Supports Composite Workloads
false
Supported Workload Types
  • All
Example
merge_actions:
  - bash:.expeditor/bump_major_version.sh:
      only_if_labels: "Version: Bump Major"
  - built_in:bump_version:
      not_if:
        - bash:.expeditor/bump_major_version.sh

only_if_conditions

Only trigger the action if all of the specified conditions are met, where the conditions are an array of hashes that specify three key-value pairs: value_one, operator, and value_two. These three values constitute an equality statement.

  • You can pass workload values as mustache parameters into either value_one or value_two.
  • Supported operators include: equals, not-equals
Default
[]
Type
Inclusive
Supports Composite Workloads
false
Supported Workload Types
  • All
Example
promote:
  actions:
    - bash:.expeditor/promote-services.sh
    - trigger_pipeline:deploy/acceptance:
        only_if_conditions:
          - value_one: "{{target_channel}}"
            operator: equals
            value_two: acceptance
  channels:
    - dev
    - acceptance
    - current
    - stable

only_if_labels

An array of Github labels that indicate that this action should only be executed if that label has been applied to the pull request.

Default
[]
Type
Inclusive
Supports Composite Workloads
true
Supported Workload Types
Example
merge_actions:
  - built_in:bump_version:
      only_if_labels: "Version: Bump Patch"

only_if_modified

Only execute this action if a modified file matches one of the path globs listed.

Default
[]
Type
Inclusive
Supports Composite Workloads
true
Supported Workload Types
Example
merge_actions:
- bash:.expeditor/update_docs.sh:
    only_if_modified:
      - docs/*
      - mkdocs.yml

only_if_team_member

Only trigger the action if the GitHub user that opened the Pull Request is a member of one of the listed teams. You must specify the team name in the form of org_slug/team_slug omitting the @.

Default
[]
Type
Inclusive
Supports Composite Workloads
true
Supported Workload Types
Example
subscriptions:
  # Automatically assign the author to the Pull Request if they belong to a certain team
  - workload: pull_request_opened:{{agent_id}}:*
    actions:
      - built_in:github_auto_assign_author:
          only_if_team_member:
            - inspec/owners
            - inspec/inspec-core-team

only_if

Only trigger the action if all of the listed actions have also triggered.

Default
[]
Type
Inclusive
Supports Composite Workloads
true
Supported Workload Types
  • All
Example
merge_actions:
  - built_in:bump_version:
      ignore_labels:
        - "Version: Skip Bump"
  - bash:.expeditor/update_version.sh:
      only_if:
        - built_in:bump_version

post_commit

Some actions (like built_in:bump_version, built_in:update_changelog, or one of your bash:* actions) may modify files that you wish to have committed directly to master. This value indicates that the specified action should wait until after any changes have been committed before triggering.

Default
Varies based on the action.
Type
internal
Supports Composite Workloads
true
Supported Workload Types
  • All
Example
merge_actions:
  - built_in:bump_version
  - bash:.expeditor/action-related-to-generated-git-tag.md:
      post_commit: true

retriable

Determines whether or not the action can be retried if it fails.

Default
Varies based on the action.
Type
internal
Supports Composite Workloads
true
Supported Workload Types
  • All
Example
merge_actions:
  - bash:.expeditor/action-related-to-generated-git-tag.md:
      retriable: false

silent

Do not include this action in any notifications.

Default
false
Type
internal
Supports Composite Workloads
true
Supported Workload Types
  • All
Example
merge_actions:
  - noop:any_action:
      silent: true