Skip to main content

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.

Default
false
Limitations
Can only be used with post-commit actions.
Sample Usage
Always unlock the local_hab_build staging area, even if our bash action fails.
.expeditor/config.yml
---
staging_areas:
	- post_merge:
      workload: pull_request_merged:{{agent_id}}:*

subscriptions:
  - workload: staged_workload_released:{{agent_id}}:post_merge:*
    actions:
      - bash:.expeditor/my-bash-script
      - 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
An empty list
Limitations
Can only be used with the actions responding to the following workloads:
Sample Usage
Do not execute the built_in:bump_version action if the Expeditor: Skip Version Bump label was applied on the GitHub pull request when it was merged.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    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
An empty list
Limitations
Can only be used with the actions responding to the following workloads:
Sample Usage
Do not execute the built_in:bump_version action if the phrases skip version or version skip are present in the pull request's title or description.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    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
An empty list
Limitations
Can only be used with the actions responding to the following workloads:
Sample Usage
Do not post a welcome message if the user belongs to one of the specified teams.
.expeditor/config.yml
---
subscriptions:
  - 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
An empty list
Limitations
Can not be used with actions executing in response to the staged_workload_released workload.
Sample Usage
We can not think of a suitable example for this functionality. If you think of one, please contact Release Engineering.

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 metadata values as mustache parameters into either value_one or value_two.
  • Supported operators include: equals, not-equals
Default
An empty list
Limitations
Can not be used with actions executing in response to the staged_workload_released workload.
Sample Usage
We're unable to find a suitable demo for this functionality. If you think you have one, please reach out to Release Engineering.

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
An empty list
Limitations
Can only be used with the actions responding to the following workloads:
Sample Usage
Only trigger the built_in:bump_version action if the Expeditor: Bump Version Patch label was applied to the pull request when it was merged.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - built_in:bump_version:
          only_if_labels:
            - "Version: Bump Version Patch"

only_if_modified

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

Default
An empty list
Limitations
Can only be used with the actions responding to the following workloads:
Sample Usage
Only trigger the .expeditor/update_docs.sh bash action if one or more of the files modified as part of the pull request match the listed glob patterns.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    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
An empty list
Limitations
Can only be used with the actions responding to the following workloads:
Sample Usage
Automatically assign the author to the GitHub pull request if they belong to one of the listed teams.
.expeditor/config.yml
---
subscriptions:
  - 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
An empty list
Sample Usage
Only run the .expeditor/update_version.sh bash action if the built_in:bump_version action completed successfully. In this example, if the Expeditor: Skip Version Bump label is applied, the built_in:bump_version action would be skipped, thus skipping the bash action as well.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    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. Please see the action reference documentation to see to which action set phase an action defaults.
Sample Usage
Run the .expeditor/action-related-to-generated-git-tag.sh bash action only after the commit and tag has been pushed to GitHub.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - built_in:bump_version
      - bash:.expeditor/action-related-to-generated-git-tag.sh:
          post_commit: true

retriable

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

Default
Varies based on the action. Please see the action reference documentation to see to which action set phase an action defaults.
Sample Usage
Mark the .expeditor/scary-bash-script.sh bash action non-retriable since it cannot be safely re-run.
.expeditor/config.yml
merge_actions:
  - bash:.expeditor/scary-bash-script.sh:
      retriable: false

silent

Only notify on this action in Slack notifications if it fails.

Default
false
Sample Usage
Trigger the batch_cron pipeline on a schedule, but only send a notification to our Slack channel if Expeditor fails to trigger a build.
.expeditor/config.yml
---
subscriptions:
  - workload: schedule_triggered:{{agent_id}}:some_schedule:*
    actions:
      - trigger_pipeline:batch_cron:
          silent: true