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:{{github_repo}}:{{release_branch}}:*

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:

• pull_request_opened
• pull_request_merged
• pull_request_closed
• pull_request_synchronized

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:{{github_repo}}:{{release_branch}}:*
    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:

• pull_request_opened
• pull_request_merged
• pull_request_closed
• pull_request_synchronized

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:{{github_repo}}:{{release_branch}}:*
    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:

• pull_request_opened
• pull_request_merged
• pull_request_closed
• pull_request_synchronized

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:{{github_repo}}:{{release_branch}}:*
    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:

• pull_request_opened
• pull_request_merged
• pull_request_closed
• pull_request_synchronized

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:{{github_repo}}:{{release_branch}}:*
    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:

• pull_request_opened
• pull_request_merged
• pull_request_closed
• pull_request_synchronized

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:{{github_repo}}:{{release_branch}}:*
    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:

• pull_request_opened
• pull_request_merged
• pull_request_closed
• pull_request_synchronized

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:{{github_repo}}:{{release_branch}}:*
    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:{{github_repo}}:{{release_branch}}:*
    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 the release branch. 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:{{github_repo}}:{{release_branch}}:*
    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

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    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