Complete reference guide

Applying the config
If you are looking for more customization options, you may want to use the YAML based configuration file. There are two ways to set up a configuration file.
From dashboard
You can directly apply the config on the Yaml configuration tab on the Merge Rules page. Here you can also validate this configuration before applying.
applying YAML configuration from dashboard
From GitHub repository
You can also create a configuration file stored in .mergequeue/config.yml. The file will only be read once it is merged into the repository's default branch. It will also override any properties set in the Dashboard UI. The only required attribute is merge_rules.labels.trigger.
Rules
Labels
merge_rules:  
  labels:    
    trigger: "label_name"    
    skip_line: "skip_line"    
    merge_failed: "blocked"    
    skip_delete_branch: "do-not-delete"
Attributes
Name
Type
Description
trigger
String
(Required). This label is used to identify that a pull request is ready to be processed by Aviator bot. Once labeled, the bot will verify that the PR has passed all the required conditions and then merge the PR.
skip_line
String
When tagged with this label, Aviator bot will move the PR to the front of the queue.
merge_failed
String
If the pull request fails to merge, Aviator bot will add this label.
skip_delete_branch
String
If delete_branch is enabled, Aviator bot will skip deleting a branch with this label after merging.
Preconditions
merge_rules:  
  labels:    
    trigger: "label_name"  
  preconditions:    
    number_of_approvals: 1    
    required_checks:
      # Note: both a string or a more detailed conditional check is accepted
      # for conditional_check, both skipped and success are considered passing      
      - check_1
      - name: conditional_check
        acceptable_statuses:
          - skipped
          - success
      - "golang-*"  # matches golang-test, golang-lint, etc.
    use_github_mergeability: true    
    conversation_resolution_required: false
    validations:
    - name: missing JIRA ticket in PR title
      match:
        type: title
        regex:
        - -\s\[[^\]]*\]
        - ()
    - name: validation_body
      match:
        type: body
        regex:
        - -\s\[[^\]]*\]yam
Attributes
​
Name
Type
Description
number_of_approvals
Integer
Minimum number of reviewers that should approve the PullRequest before it can qualify to be merged. Defaults to 1.
required_checks
List[Union[String, ConditionalCheck]]
Checks that need to pass before Aviator bot will merge the PR. Supports shell wildcard (glob) patterns. Also supports other acceptable CI statuses if your repo uses conditional status checks. See the Example tab.
​
use_github_mergeability
Boolean
Determines whether to use the default required checks specified in branch protection rules on GitHub. When this setting is enabled, Aviator bot will ignore required_checks. Defaults to true.
conversation_resolution_required
Boolean
Determines whether Aviator bot will queue the PR only after all conversations are resolved. Defaults to false.
validations
List[Validation]
Custom validation rules using regexes for the PR body or title. See the Example tab for more details.
Merge Modes
Name
Type
Description
type
String
Determines the mode. Options are: default, parallel, no-queue.
Parallel Mode
The following are only applicable if the above merge_mode is set to parallel. You can learn more about Parallel Mode here.
merge_rules:  
  labels:    
    trigger: "label_name"  
  merge_mode:    
    type: "parallel" # other modes: "default", "no-queue"    
    parallel_mode:      
      use_affected_targets: false
      use_fast_forwarding: true      
      max_parallel_builds: 10
      max_parallel_paused_builds: 1      
      max_requeue_attempts: 3
      update_before_requeue: true
      stuck_pr_label: "label"      
      stuck_pr_timeout_mins: 90      
      block_parallel_builds_label: "block_batch"      
      check_mergeability_to_queue: false
      override_required_checks:
        - "check 1"
        - check_2
        # Note: both a string or a more detailed conditional check is accepted
        # for conditional_check, both skipped and success are considered passing      
        - name: conditional_check
          acceptable_statuses:
            - skipped
            - success
      batch_size: 1
      batch_max_wait_minutes: 0
      require_all_draft_checks_pass: false
      skip_draft_when_up_to_date: false
      use_optimistic_validation: true
      optimistic_validation_failure_depth: 2
Attributes
​
Name
Type
Description
max_parallel_builds
Integer
The maximum number of builds that Aviator bot will run at any time. Defaults to no limit.
max_parallel_paused_builds
Integer
Must be less than max_parallel_builds. Defaults to null. 

The maximum number of PRs in a paused state that Aviator will create draft PRs for.  If set to 0, Aviator will not create any draft PRs on paused base branches. If set to null there will be no specific limit for paused PRs.

The number of paused draft PRs always counts towards the cap set by max_parallel_builds.
max_requeue_attempts
Integer
The maximum number of times Aviator bot will requeue a CI run after failing. Note that PRs will only be requeued if the original PR CI is passing but the draft PR CI fails. Defaults to no requeuing.
update_before_requeue
Boolean
Whether to update the PR with the base branch when doing an auto-requeue. This is only applicable if max_requeue_attempts is set. Defaults to false.
stuck_pr_label
String
The label that Aviator bot will add if it determines a PR to be stuck.
stuck_pr_timeout_mins
Integer
Aviator bot will determine the PR to be stuck after the specified timeout and dequeue it. A stuck state in parallel mode is when the draft PR has passed CI but the original PR's CI is still pending. Defaults to 0, which means that Aviator will dequeue the PR immediately.
block_parallel_builds_label
String
Once added to a PR, no further Draft PRs will be built on top of it until that PR is merged or dequeued.
check_mergeability_to_queue
Boolean
If enabled, Aviator bot will only queue the PR if it passes all mergeability checks. Defaults to false.
use_affected_targets
Boolean
If enabled, allows using affected targets in your repo.
use_fast_forwarding
Boolean
If enabled, uses fast forwarding to merge PRs.
override_required_checks
List[Union[String, ConditionalCheck]]
Use this attribute if you would like different checks for your original PRs and draft PRs. The checks defined here will be used for the draft PRs created in Parallel mode. Supports shell wildcard (glob) patterns. Also supports other acceptable CI statuses if your repo uses conditional status checks. See the Example tab.
batch_size
Integer
The number of queued PRs batched together for a draft PR CI run. Defaults to 1.
batch_max_wait_minutes
Integer
The time to wait before creating the next batch of PRs if there are not enough queued PRs to create a full batch. Defaults to 0.
require_all_draft_checks_pass
Boolean
Determines if Aviator will enforce all checks to pass for the constructed draft PRs. If true, any single failing test will cause the draft PR to fail. These checks include the ones we receive status updates for via GitHub. This may work well if your repo has conditional checks. Requires at least one check to be present. Defaults to false.
skip_draft_when_up_to_date
Boolean
Skips creation of the staging draft PR to validate the CI if the original PR is already up to date and no other PR is currently queued. This is usually a good optimization to avoid running extra CI cycles. Defaults to true.
use_optimistic_validation
Boolean
If the CI of the top staging draft PR is still running but a subsequent draft PR passes, then optimistically use that success result to validate the top PR as passing. Defaults to true.
optimistic_validation_failure_depth
Integer
Requires use_optimistic_validation to be true. If the CI of the top staging draft PR has failed, wait for subsequent draft PR CIs to also fail before dequeuing the PR. The number represents how many draft PRs do we wait to fail before dequeuing a PR. For e.g., if set to 1, it will dequeue immediately after the top staging draft PR fails, but if set to 2, it will wait for one more subsequent draft PR to fail before dequeuing the top PR. Value should always be 1 or larger. Defaults to 1.
​
Auto Update
merge_rules:  
  labels:    
    trigger: "label_name"  
  auto_update:    
    enabled: true    
    label: "auto_update"    
    max_runs_for_update: 10
Attributes
Name
Type
Description
enabled
Boolean
If enabled, Aviator bot will keep your branches up to date with the main branch. Defaults to false.
label
String
Aviator bot will only keep branches with this label up to date with the main branch. Leave empty to auto merge without a label. If no label is provided and auto_update is enabled, by default the Aviator bot will update all PRs.
max_runs_for_update
Integer
The maximum number of times Aviator bot will update your branch. Defaults to no limit.
Merge Commit
merge_rules:
  labels:
    trigger: "label_name"
  merge_commit:
    use_title_and_body: true
    cut_body_before: "----"
    cut_body_after: "+++"
    strip_html_comments: false
    include_coauthors: true
    apply_title_regexes:
      - pattern: "AVTR-"
        replace: "AVTR_"
      - pattern: "MQ-BOT"
        replace: "MQ BOT"
Attributes
Name
Type
Description
use_title_and_body
Boolean
Determines whether Aviator bot will replace default commit messages offered by GitHub. Defaults to false.
cut_body_before
String
A marker string to cut the PR body description. The commit message will contain the PR body after this marker. Leave empty for no cropping.
cut_body_after
String
A marker string to cut the PR body description. The commit message will contain the PR body before this marker. Leave empty for no cropping.
strip_html_comments
Boolean
Strip out the hidden HTML comments from the commit message when merging the PR. Defaults to false.
include_coauthors
Boolean
Include coauthors (if any) in the commit message when merging the PR. Defaults to true.
apply_title_regexes
List[ReplacePattern]
Contains the strings pattern and replace to indicate what pattern to replace in the PR title. This will be applied to the merge commit. In parallel mode, this also applies to the draft PR title. See the example tab for more details.
Merge Strategy
Name
Type
Description
name
String
Defines the merge strategy to use, the options are "squash", "merge", and "rebase". See the GitHub docs for more info.
Override Labels
You can specify overrides to the above merge strategy using GitHub Labels. When a PR is flagged with these labels along with the trigger label, Aviator bot will merge the PR using this strategy instead of the default strategy. Leave empty for no overrides.
merge_rules:
  labels:
    trigger: "label_name"
  merge_strategy:
    name: "squash"
    override_labels:
      squash: "mq-squash"
      merge: "mq-merge-commit"
      rebase: "mq-rebase"
Attributes
Name
Type
Description
squash
String
If marked with this label, the PR will be squashed and merged.
merge
String
If marked with this label, the PR will be merged using a merge commit.
rebase
String
If marked with this label, the PR will be rebased and merged.
Status Comment
Aviator posts a status comment on every open pull request by default. Aviator automatically updates the status comment whenever the pull request is updated.
Custom messages can be specified (open_message, queued_message, and blocked_message) to add information specific to your organization or repository (such as common troubleshooting steps).
merge_rules:
  # Configuration for the Aviator status comment.
  # Optional (defaults to publish: "always" with no custom messages).
  status_comment:
    # When to publish the Aviator status comment.
    # Optional. Valid values are "always", "queued", or "never".
    # Default value is "always".
    #   - "always": Post the status comment whenever the pull request is opened.
    #   - "ready": Publish the status comment when the pull request is ready for review.
    #   - "queued": Post the status comment when the pull request is queued.
    #   - "never": Disable the status comment.
    publish: "always"
    
    # A message to include in the status comment if the pull request is in the
    # open state. Supports markdown.
    # Optional.
    open_message: "..."
    
    # A message to include in the status comment if the pull request is in the
    # queued state. Supports markdown.
    # Optional.
    queued_message: "..."
    
    # A message to include in the status comment if the pull request is in the
    # blocked state. Supports markdown.
    # Optional.
    blocked_message: "..."
Attributes
​
Name
Type
Description
publish
String
One of always, ready, queued, or never. Defaults to always.
open_message
String
An optional message to include in the Aviator status comment when the pull request is open (not queued).
queued_message
String
An optional message to include in the Aviator status comment when the pull request is queued.
blocked_message
String
An optional message to include in the Aviator status comment when the pull request is blocked.
Other
merge_rules:
  labels:
    trigger: "label_name"
  update_latest: true
  delete_branch: false
  use_rebase: false
  publish_status_check: "ready"
  enable_comments: true
  ci_timeout_mins: 60
  base_branches:
    - master
    - /release-*/
Attributes
​
Name
Type
Description
update_latest
Boolean
Determines whether Aviator bot will merge the latest base branch into the current branch of your PR before verifying the CI statuses. This is only compatible with the default and no-queue merge modes. Defaults to true.
delete_branch
Boolean
Determines whether Aviator bot will delete the branch after merging. Defaults to false.
use_rebase
Boolean
Determines if Aviator bot will use rebase to update PRs. This feature is only available in the Pro plan. Please note that you also need to enable update_latest for rebase to work. Defaults to false.
publish_status_check
Boolean or String
Determines if Aviator bot will publish a status check back on the PR. This status check represents the current state of PR in the Aviator queue.

Possible values:
always: Post the status check whenever the pull request is opened.
ready: Publish the status check when the pull request is ready for review.
queued: Post the status comment when the pull request is queued.
never: Disable the status comment.

For backward compatibility this value also supports boolean.
true same as ready
false same as never

Defaults to ready
enable_comments
Boolean
Determines if Aviator bot can add comments on the PR to describe the actions performed on the PR by the bot. Aviator bot comments include information such as failure reasons and the position of the PR in the queue. Defaults to true.
ci_timeout_mins
Integer
The time before we determine that the CI has timed out. Defaults to no time out.
base_branches
List[String]
These branches are the ones that Aviator will monitor as valid branches to merge into. Defaults to your repository default branch as configured on GitHub. Regexes are allowed.
require_all_checks_pass
Boolean
Determines if Aviator will enforce all checks to pass. If true, any single failing test will cause the PR to fail. These checks include the ones we receive status updates for via GitHub. This may work well if your repo has conditional checks. Requires at least one check to be present. Defaults to false.

Name	Type	Description
trigger	String	(Required). This label is used to identify that a pull request is ready to be processed by Aviator bot. Once labeled, the bot will verify that the PR has passed all the required conditions and then merge the PR.
skip_line	String	When tagged with this label, Aviator bot will move the PR to the front of the queue.
merge_failed	String	If the pull request fails to merge, Aviator bot will add this label.
skip_delete_branch	String	If `delete_branch` is enabled, Aviator bot will skip deleting a branch with this label after merging.

Name	Type	Description
number_of_approvals	Integer	Minimum number of reviewers that should approve the PullRequest before it can qualify to be merged. Defaults to 1.
required_checks	List[Union[String, ConditionalCheck]]	Checks that need to pass before Aviator bot will merge the PR. Supports shell wildcard (glob) patterns. Also supports other acceptable CI statuses if your repo uses conditional status checks. See the Example tab.
use_github_mergeability	Boolean	Determines whether to use the default required checks specified in branch protection rules on GitHub. When this setting is enabled, Aviator bot will ignore `required_checks`. Defaults to `true`.
conversation_resolution_required	Boolean	Determines whether Aviator bot will queue the PR only after all conversations are resolved. Defaults to `false`.
validations	List[Validation]	Custom validation rules using regexes for the PR body or title. See the Example tab for more details.

Name	Type	Description
type	String	Determines the mode. Options are: default, parallel, no-queue.

Name	Type	Description
max_parallel_builds	Integer	The maximum number of builds that Aviator bot will run at any time. Defaults to no limit.
max_parallel_paused_builds	Integer	Must be less than `max_parallel_builds`. Defaults to `null`. The maximum number of PRs in a paused state that Aviator will create draft PRs for. If set to 0, Aviator will not create any draft PRs on paused base branches. If set to `null` there will be no specific limit for paused PRs. The number of paused draft PRs always counts towards the cap set by `max_parallel_builds`.
max_requeue_attempts	Integer	The maximum number of times Aviator bot will requeue a CI run after failing. Note that PRs will only be requeued if the original PR CI is passing but the draft PR CI fails. Defaults to no requeuing.
update_before_requeue	Boolean	Whether to update the PR with the base branch when doing an auto-requeue. This is only applicable if `max_requeue_attempts` is set. Defaults to `false`.
stuck_pr_label	String	The label that Aviator bot will add if it determines a PR to be stuck.
stuck_pr_timeout_mins	Integer	Aviator bot will determine the PR to be stuck after the specified timeout and dequeue it. A stuck state in parallel mode is when the draft PR has passed CI but the original PR's CI is still pending. Defaults to 0, which means that Aviator will dequeue the PR immediately.
block_parallel_builds_label	String	Once added to a PR, no further Draft PRs will be built on top of it until that PR is merged or dequeued.
check_mergeability_to_queue	Boolean	If enabled, Aviator bot will only queue the PR if it passes all mergeability checks. Defaults to `false`.
use_affected_targets	Boolean	If enabled, allows using affected targets in your repo.
use_fast_forwarding	Boolean	If enabled, uses fast forwarding to merge PRs.
override_required_checks	List[Union[String, ConditionalCheck]]	Use this attribute if you would like different checks for your original PRs and draft PRs. The checks defined here will be used for the draft PRs created in Parallel mode. Supports shell wildcard (glob) patterns. Also supports other acceptable CI statuses if your repo uses conditional status checks. See the Example tab.
batch_size	Integer	The number of queued PRs batched together for a draft PR CI run. Defaults to 1.
batch_max_wait_minutes	Integer	The time to wait before creating the next batch of PRs if there are not enough queued PRs to create a full batch. Defaults to 0.
require_all_draft_checks_pass	Boolean	Determines if Aviator will enforce all checks to pass for the constructed draft PRs. If true, any single failing test will cause the draft PR to fail. These checks include the ones we receive status updates for via GitHub. This may work well if your repo has conditional checks. Requires at least one check to be present. Defaults to `false`.
skip_draft_when_up_to_date	Boolean	Skips creation of the staging draft PR to validate the CI if the original PR is already up to date and no other PR is currently queued. This is usually a good optimization to avoid running extra CI cycles. Defaults to `true`.
use_optimistic_validation	Boolean	If the CI of the top staging draft PR is still running but a subsequent draft PR passes, then optimistically use that success result to validate the top PR as passing. Defaults to `true`.
optimistic_validation_failure_depth	Integer	Requires `use_optimistic_validation` to be `true`. If the CI of the top staging draft PR has failed, wait for subsequent draft PR CIs to also fail before dequeuing the PR. The number represents how many draft PRs do we wait to fail before dequeuing a PR. For e.g., if set to 1, it will dequeue immediately after the top staging draft PR fails, but if set to 2, it will wait for one more subsequent draft PR to fail before dequeuing the top PR. Value should always be `1` or larger. Defaults to `1`.

Name	Type	Description
enabled	Boolean	If enabled, Aviator bot will keep your branches up to date with the main branch. Defaults to `false`.
label	String	Aviator bot will only keep branches with this label up to date with the main branch. Leave empty to auto merge without a label. If no label is provided and `auto_update` is enabled, by default the Aviator bot will update all PRs.
max_runs_for_update	Integer	The maximum number of times Aviator bot will update your branch. Defaults to no limit.

Name	Type	Description
use_title_and_body	Boolean	Determines whether Aviator bot will replace default commit messages offered by GitHub. Defaults to `false`.
cut_body_before	String	A marker string to cut the PR body description. The commit message will contain the PR body after this marker. Leave empty for no cropping.
cut_body_after	String	A marker string to cut the PR body description. The commit message will contain the PR body before this marker. Leave empty for no cropping.
strip_html_comments	Boolean	Strip out the hidden HTML comments from the commit message when merging the PR. Defaults to `false`.
include_coauthors	Boolean	Include coauthors (if any) in the commit message when merging the PR. Defaults to `true`.
apply_title_regexes	List[ReplacePattern]	Contains the strings `pattern` and `replace` to indicate what pattern to replace in the PR title. This will be applied to the merge commit. In parallel mode, this also applies to the draft PR title. See the example tab for more details.

Name	Type	Description
name	String	Defines the merge strategy to use, the options are "squash", "merge", and "rebase". See the GitHub docs for more info.

Name	Type	Description
squash	String	If marked with this label, the PR will be squashed and merged.
merge	String	If marked with this label, the PR will be merged using a merge commit.
rebase	String	If marked with this label, the PR will be rebased and merged.

Name	Type	Description
publish	String	One of `always`, `ready`, `queued`, or `never`. Defaults to `always`.
open_message	String	An optional message to include in the Aviator status comment when the pull request is open (not queued).
queued_message	String	An optional message to include in the Aviator status comment when the pull request is queued.
blocked_message	String	An optional message to include in the Aviator status comment when the pull request is blocked.

Name	Type	Description
update_latest	Boolean	Determines whether Aviator bot will merge the latest base branch into the current branch of your PR before verifying the CI statuses. This is only compatible with the `default` and `no-queue` merge modes. Defaults to `true`.
delete_branch	Boolean	Determines whether Aviator bot will delete the branch after merging. Defaults to `false`.
use_rebase	Boolean	Determines if Aviator bot will use rebase to update PRs. This feature is only available in the Pro plan. Please note that you also need to enable `update_latest` for rebase to work. Defaults to `false`.
publish_status_check	Boolean or String	Determines if Aviator bot will publish a status check back on the PR. This status check represents the current state of PR in the Aviator queue. Possible values: `always`: Post the status check whenever the pull request is opened. `ready`: Publish the status check when the pull request is ready for review. `queued`: Post the status comment when the pull request is queued. `never`: Disable the status comment. For backward compatibility this value also supports boolean. `true` same as `ready` `false` same as `never`Defaults to `ready`
enable_comments	Boolean	Determines if Aviator bot can add comments on the PR to describe the actions performed on the PR by the bot. Aviator bot comments include information such as failure reasons and the position of the PR in the queue. Defaults to `true`.
ci_timeout_mins	Integer	The time before we determine that the CI has timed out. Defaults to no time out.
base_branches	List[String]	These branches are the ones that Aviator will monitor as valid branches to merge into. Defaults to your repository default branch as configured on GitHub. Regexes are allowed.
require_all_checks_pass	Boolean	Determines if Aviator will enforce all checks to pass. If true, any single failing test will cause the PR to fail. These checks include the ones we receive status updates for via GitHub. This may work well if your repo has conditional checks. Requires at least one check to be present. Defaults to `false`.

Configuration file

Audit Trail

Last modified 1mo ago