Mergify Configuration

Mergify configuration file

Type object
File match .mergify.yml **/.github/mergify.yml **/.mergify/config.yml
Schema URL https://catalog.lintel.tools/schemas/github/mergify-configuration/latest.json
Source https://raw.githubusercontent.com/Mergifyio/docs/main/public/mergify-configuration-schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Properties

shared object | null
Default: null
extends string | null
Default: null
defaults object
2 nested properties
actions object
18 nested properties
assign AssignActionModel | null
Default: null
backport BackportActionModel | null
Default: null
close CloseActionModel | null
Default: null
comment CommentActionModel | null
Default: null
copy CopyActionModel | null
Default: null
delete_head_branch DeleteHeadBranchActionModel | null
Default: null
dismiss_reviews DismissReviewsActionModel | null
Default: null
edit EditActionModel | null
Default: null
github_actions GhaActionModel | null
Default: null
label LabelActionModel | null
Default: null
merge MergeActionModel | null
Default: null
post_check PostCheckActionModel | null
Default: null
queue QueueActionModel | null
Default: null
rebase RebaseActionModel | null
Default: null
request_reviews RequestReviewsActionModel | null
Default: null
review ReviewActionModel | null
Default: null
squash SquashActionModel | null
Default: null
update UpdateActionModel | null
Default: null
queue_rule QueueRuleModelForDefaults | null
Default: null
scopes object
2 nested properties
source SourceFiles | SourceManual | null

Where scopes come from. files uses file-pattern rules (gha-mergify-ci-scopes must have been setup on your pull request); manual uses scopes sent via API or mergify scopes-send; None disables scoping.

Default: null
merge_queue_scope string

Scope name automatically applied to merge queue PRs.

Default: "merge-queue"
minLength=2pattern=^[A-Za-z0-9_-]+$
commands_restrictions object
10 nested properties
backport object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
copy object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
dequeue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
queue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
rebase object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
refresh object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
requeue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
squash object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
unqueue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
update object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
pull_request_rules PullRequestRuleModel[]
maxItems=200
queue_rules QueueRuleModel[]
maxItems=50
partition_rules PartitionRuleModel[]
maxItems=50
merge_protections MergeProtectionRuleModel[]
maxItems=100
priority_rules PriorityRuleModel[]
maxItems=50
merge_queue object
7 nested properties
max_parallel_checks integer

The maximum number of speculative checks allowed to run at the same time. Setting this value to 1 disables speculative checks.

Default: 5
min=1max=128
reset_on_external_merge string

Defines the behavior of the merge queue when something is merged outside of the queue. "always": The queue is reset when an external merge is detected. All queued pull requests are re-evaluated to ensure correctness based on the new base branch state. "never": The queue remains unchanged. It does not reset or re-evaluate based on the external merge.

Default: "always"
Values: "never" "always"
queued_label string | null

The label to add on pull requests when they are added to the merge queue.

Default: "queued"
dequeued_label string | null

The label to add on pull requests when they are removed from the merge queue.

Default: "dequeued"
mode string

Defines how the merge queue schedules pull requests.

  • serial: PRs are tested cumulatively.
  • parallel: PRs whose scopes don't overlap are tested in parallel.
Default: "serial"
Values: "serial" "parallel"
skip_intermediate_results boolean

Allow PRs to merge even if their own speculative check fails, as long as a later downstream check including them passes and schedule conditions are valid.

Default: false
status_comments string

Controls the level of status comments posted on pull requests in the queue.

  • all: Post comments for all queue events (entering queue, CI progress, outcomes).
  • outcomes: Only post comments for final outcomes (merged or dequeued with failure reason).
  • none: Do not post any comments for queue status.
Default: "all"
Values: "all" "outcomes" "none"
merge_protections_settings object
2 nested properties
reporting_method string

The merge protection reporting method

Default: "check-runs"
Values: "check-runs" "deployments"
post_comment boolean

Whether to post merge protection status comments on pull requests

Default: true

Definitions

ActionsModel object
assign AssignActionModel | null
Default: null
backport BackportActionModel | null
Default: null
close CloseActionModel | null
Default: null
comment CommentActionModel | null
Default: null
copy CopyActionModel | null
Default: null
delete_head_branch DeleteHeadBranchActionModel | null
Default: null
dismiss_reviews DismissReviewsActionModel | null
Default: null
edit EditActionModel | null
Default: null
github_actions GhaActionModel | null
Default: null
label LabelActionModel | null
Default: null
merge MergeActionModel | null
Default: null
post_check PostCheckActionModel | null
Default: null
queue QueueActionModel | null
Default: null
rebase RebaseActionModel | null
Default: null
request_reviews RequestReviewsActionModel | null
Default: null
review ReviewActionModel | null
Default: null
squash SquashActionModel | null
Default: null
update UpdateActionModel | null
Default: null
AndCondition object
and AndCondition | OrCondition | NegationCondition | RuleConditionModel[] required
maxItems=500
AssignActionModel object
users string[]
maxItems=10
add_users string[]
maxItems=10
remove_users string[]
maxItems=40
BackportActionModel object
bot_account string | null

Mergify can impersonate a GitHub user to copy a pull request. If no bot_account is set, Mergify copies the pull request itself.

Default: null
branches BranchName[]

The list of branches the pull request should be copied to.

maxItems=30
regexes string[]

The list of regexes to find branches the pull request should be copied to.

maxItems=30
ignore_conflicts boolean

Whether to create the pull requests even if there are conflicts when cherry-picking the commits.

Default: true
assignees string[]

Users to assign the newly created pull request to. As the type is a data type template, you could use, e.g., {{author}} to assign the pull request to its original author.

maxItems=10
labels string[]

The list of labels to add to the created pull requests.

maxItems=30
label_conflicts string

The label to add to the created pull request if it has conflicts and ignore_conflicts is set to true.

Default: "conflicts"
title string

The pull request's title.

Default: "{{ title }} (backport #{{ number }})"
format=template
body string

The pull request's body.

Default: "{{ body }}<hr>This is an automatic backport of pull request #{{number}} done by [Mergify](https://mergify.com). "
format=template
report_mode string[]

Reporting modes for the action's result. Check will create a check on the pull request, and comment will post a comment on the pull request.

Default:
[
  "check"
]
minItems=1
merge_conflict_style string

Style used by git when displaying merge conflicts

Default: "merge"
Values: "merge" "diff3"
BranchName string

A Git branch name.

CloseActionModel object
message string

A string template using the Jinja2 syntax.

Default: "This pull request has been automatically closed by Mergify."
format=template
CommandRestrictionsConditionsModel AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
CommandRestrictionsModel object
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
CommandsRestrictionsRulesModel object
backport object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
copy object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
dequeue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
queue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
rebase object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
refresh object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
requeue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
squash object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
unqueue object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
update object
1 nested properties
conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
CommentActionModel object
message string | null

The message to write as a comment.

Default: null
bot_account string | null

Mergify can impersonate a GitHub user to comment a pull request. If no bot_account is set, Mergify will comment the pull request itself.

Default: null
Commit object
sha string required
parents string[] required
commit_message string required
commit_verification_verified boolean required

Indicates if the commit has been marked as verified by GitHub

author string | null required

Name of the author

committer string | null required

Name of the committer

date_author string | null required
date_committer string | null required
email_author string | null required
email_committer string | null required
gh_author_login string | null required

GitHub login of the author

CommitAuthor object
name string | null required

Name of the author

email string | null required

Email address of the author

CopyActionModel object
bot_account string | null

Mergify can impersonate a GitHub user to copy a pull request. If no bot_account is set, Mergify copies the pull request itself.

Default: null
branches BranchName[]

The list of branches the pull request should be copied to.

maxItems=30
regexes string[]

The list of regexes to find branches the pull request should be copied to.

maxItems=30
ignore_conflicts boolean

Whether to create the pull requests even if there are conflicts when cherry-picking the commits.

Default: true
assignees string[]

Users to assign the newly created pull request to. As the type is a data type template, you could use, e.g., {{author}} to assign the pull request to its original author.

maxItems=10
labels string[]

The list of labels to add to the created pull requests.

maxItems=30
label_conflicts string

The label to add to the created pull request if it has conflicts and ignore_conflicts is set to true.

Default: "conflicts"
title string

The pull request's title.

Default: "{{ title }} (copy #{{ number }})"
format=template
body string

The pull request's body.

Default: "{{ body }}<hr>This is an automatic copy of pull request #{{number}} done by [Mergify](https://mergify.com). "
format=template
report_mode string[]

Reporting modes for the action's result. Check will create a check on the pull request, and comment will post a comment on the pull request.

Default:
[
  "check"
]
minItems=1
merge_conflict_style string

Style used by git when displaying merge conflicts

Default: "merge"
Values: "merge" "diff3"
DefaultsRulesModel object
actions object
18 nested properties
assign AssignActionModel | null
Default: null
backport BackportActionModel | null
Default: null
close CloseActionModel | null
Default: null
comment CommentActionModel | null
Default: null
copy CopyActionModel | null
Default: null
delete_head_branch DeleteHeadBranchActionModel | null
Default: null
dismiss_reviews DismissReviewsActionModel | null
Default: null
edit EditActionModel | null
Default: null
github_actions GhaActionModel | null
Default: null
label LabelActionModel | null
Default: null
merge MergeActionModel | null
Default: null
post_check PostCheckActionModel | null
Default: null
queue QueueActionModel | null
Default: null
rebase RebaseActionModel | null
Default: null
request_reviews RequestReviewsActionModel | null
Default: null
review ReviewActionModel | null
Default: null
squash SquashActionModel | null
Default: null
update UpdateActionModel | null
Default: null
queue_rule QueueRuleModelForDefaults | null
Default: null
DeleteHeadBranchActionModel object
force boolean

If set to true, the branch will be deleted even if another pull request depends on the head branch. GitHub will therefore close the dependent pull requests.

Default: false
DisabledDict object
reason string required
DismissReviewsActionModel object
approved string[] | boolean | string

If set to true, all the approving reviews will be removed when the pull request is updated. If set to false, nothing will be done. If set to a list, each item should be the GitHub login of a user whose review will be removed. If set to from_requested_reviewers, the list of requested reviewers will be used to get whose review will be removed.

Default: true
changes_requested string[] | boolean | string

If set to true, all the reviews requesting changes will be removed when the pull request is updated. If set to false, nothing will be done. If set to a list, each item should be the GitHub login of a user whose review will be removed. If set to from_requested_reviewers, the list of requested reviewers will be used to get whose review will be removed.

Default: true
message string | null

Message to use when dismissing reviews.

Default: null
when string

If set to synchronize, the action will run only if the pull request commits changed. Otherwise, it will run each time the rule matches.

Default: "synchronize"
Values: "synchronize" "always"
EditActionModel object
bot_account string | null
Default: null
draft boolean | null

If the pull request should be a draft (true) or the other way around (false).

Default: null
FileFilters object
include string[]

Glob patterns of files to include for this scope. Empty means 'include everything' before exclusions. Examples: ('src/**/*.py', 'Makefile')

exclude string[]

Glob patterns of files to exclude from this scope. Evaluated after include and takes precedence. Examples: ('/tests/', '*.md')

GhaActionModel object
workflow object required

GitHub Actions workflow action

1 nested properties
dispatch GhaActionModelDispatch[]

The list of workflows to dispatch via the action.

maxItems=10
GhaActionModelDispatch object

GitHub Actions workflow dispatch

workflow string required

The name of the .yaml GitHub Workflow file with its extension.

ref string | null

The reference to use when triggering the job. If none is passed, the default repository branch is used.

Default: null
inputs Record<string, integer | boolean | string>

The inputs passed to your workflow execution if any. Values can be either a template, a number or a Boolean.

GhaActionModelWorkflow object

GitHub Actions workflow action

dispatch GhaActionModelDispatch[]

The list of workflows to dispatch via the action.

maxItems=10
GitHubRepositoryPermission string
LabelActionModel object

Add or remove labels on a pull request.

add string[]

The list of labels to add.

maxItems=50
remove string[]

The list of labels to remove.

maxItems=50
remove_all boolean

Remove all labels from the pull request.

Default: false
toggle string[]

Toggle labels in the list based on the conditions. If all the conditions are a success, all the labels in the list will be added, otherwise, they will all be removed.

maxItems=50
ListOfRuleConditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
MergeActionModel object
method string | null

Merge method to use. If no value is set, Mergify uses the first authorized method available in the repository configuration.

Default: null
merge_bot_account string | null

Mergify can impersonate a GitHub user to merge pull requests. If no merge_bot_account is set, Mergify merges the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission.

Default: null
commit_message_template string | null

Template to use as the commit message when using the merge or squash merge method.

Default: null
MergeProtectionRuleConditionsModel AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
MergeProtectionRuleModel object
name string required

The name of the rule

if AndCondition | OrCondition | NegationCondition | RuleConditionModel[] required
maxItems=500
success_conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[] required
maxItems=500
description string | null

A description of the rule

Default: null
MergeProtectionRulesModel MergeProtectionRuleModel[]
MergeProtections object
reporting_method string

The merge protection reporting method

Default: "check-runs"
Values: "check-runs" "deployments"
post_comment boolean

Whether to post merge protection status comments on pull requests

Default: true
MergeQueue object
max_parallel_checks integer

The maximum number of speculative checks allowed to run at the same time. Setting this value to 1 disables speculative checks.

Default: 5
min=1max=128
reset_on_external_merge string

Defines the behavior of the merge queue when something is merged outside of the queue. "always": The queue is reset when an external merge is detected. All queued pull requests are re-evaluated to ensure correctness based on the new base branch state. "never": The queue remains unchanged. It does not reset or re-evaluate based on the external merge.

Default: "always"
Values: "never" "always"
queued_label string | null

The label to add on pull requests when they are added to the merge queue.

Default: "queued"
dequeued_label string | null

The label to add on pull requests when they are removed from the merge queue.

Default: "dequeued"
mode string

Defines how the merge queue schedules pull requests.

  • serial: PRs are tested cumulatively.
  • parallel: PRs whose scopes don't overlap are tested in parallel.
Default: "serial"
Values: "serial" "parallel"
skip_intermediate_results boolean

Allow PRs to merge even if their own speculative check fails, as long as a later downstream check including them passes and schedule conditions are valid.

Default: false
status_comments string

Controls the level of status comments posted on pull requests in the queue.

  • all: Post comments for all queue events (entering queue, CI progress, outcomes).
  • outcomes: Only post comments for final outcomes (merged or dequeued with failure reason).
  • none: Do not post any comments for queue status.
Default: "all"
Values: "all" "outcomes" "none"
NegationCondition object
not AndCondition | OrCondition | RuleConditionModel required
OrCondition object
or AndCondition | OrCondition | NegationCondition | RuleConditionModel[] required
maxItems=500
PartitionRuleConditionsModel AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
PartitionRuleModel object
name string required

Name of the partition

conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
fallback_partition boolean

Allow the partition to work as the fallback partition. There can be only one fallback partition.

Default: false
PartitionRulesModel PartitionRuleModel[]
PostCheckActionModel object
title string

The title of the check.

Default: "'{{ check_rule_name }}'{% if check_status == 'success' %} succeeded{% elif check_status == 'failure' %} failed{% endif %}"
format=template
summary string

The summary of the check.

Default: "{{ check_conditions }}"
format=template
success_conditions ListOfRuleConditions | null

List of conditions to match to mark the pull request check as succeeded, otherwise, it will be marked as failing. If unset, the conditions from the rule that triggers this action are used.

Default: null
neutral_conditions ListOfRuleConditions | null

List of conditions to match to mark the pull request check as neutral, otherwise, it will be marked as failing.

Default: null
PriorityRuleConditionsModel AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
PriorityRuleModel object
name string required

Name of the rule.

conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[] required
maxItems=500
priority string | integer

The priority of the pull request.

Default: "medium"
allow_checks_interruption boolean

Allow interrupting the ongoing checks when the pull request entering the queue has a higher priority than the queued one(s). If set to false, a pull request with higher priority will be inserted just after the pull requests that have checks running.

Default: true
PriorityRulesModel PriorityRuleModel[]
PullRequestAttributes object
draft boolean required

Whether the pull request is in draft state.

merged boolean required

Whether the pull request is merged.

mergify-configuration-changed boolean required

Whether the pull request contains changes in the configuration file.

closed boolean required

Whether the pull request is closed.

locked boolean required

Whether the pull request is locked.

linear-history boolean required

Whether the pull request commits history is linear (no merge commit).

conflict boolean required

Whether the pull request is conflicting with its base branch.

branch-protection-review-decision string | null required

The review decision. This indicates if CODEOWNERS have reviewed the pull request when the Require Review from Code Owners branch protection rule is enabled.

number integer required

The pull request number.

min=0max=9223372036854775807
queue-position integer required

The position of the pull request in its queue if queued. The first pull request in the queue has position 0. The value is set to -1 if the pull request is not queued.

author string required

The GitHub user or team login of the author of the pull request.

merged-by string | null required

The GitHub user that merged the pull request.

merge-commit-sha string | null required

The merge commit SHA of the pull request returned by GitHub.

milestone string | null required

The milestone title associated to the pull request.

base string required

The name of the branch the pull request should be pulled into.

head string required

The name of the branch where the pull request changes are implemented.

head-repo-full-name string required

The head branch repository full name (complete version with the organization name).

title string required

The title of the pull request.

body string required

The content of the pull request description without Markdown/HTML comments.

body-raw string required

The content of the pull request description.

repository-name string required

The current repository name (short version without the organization name).

repository-full-name string required

The current repository full name (complete version with the organization name).

queue-dequeue-reason string | string | string | null required

A dequeue code for when a pull request has been disembarked from the merge queue.

queue-name string | null required

The name of the queue containing the pull request.

assignee string[] required

The list of GitHub user or team login that are assigned to the pull request. Team logins are prefixed with the @ character and must belong to the repository organization.

label string[] required

The list of labels of the pull request.

review-requested string[] required

The list of GitHub user or team login that were requested to review the pull request. Team logins are prefixed with the @ character. This only matches reviewers with admin, write or maintain permission on the repository.

approved-reviews-by string[] required

The list of GitHub user or team login that approved the pull request. Team logins are prefixed with the @ character and must belong to the repository organization. This only matches reviewers with admin, write or maintain permission on the repository.

dismissed-reviews-by string[] required

The list of GitHub user login that have their review dismissed in the pull request.

changes-requested-reviews-by string[] required

The list of GitHub user or team login that have requested changes in a review for the pull request.

commented-reviews-by string[] required

The list of GitHub user that have commented in a review for the pull request. This only matches reviewers with admin, write or maintain permission on the repository.

check-success string[] required

The list of checks that successfully passed for the pull request.

check-failure string[] required

The list of checks that failed for the pull request. Checks that report being cancelled, timed out, and action required are also considered as failures.

check-neutral string[] required

The list of checks that are neutral for the pull request.

check-timed-out string[] required

The list of checks that timed out for the pull request.

check-skipped string[] required

The list of checks that was skipped for the pull request.

check-pending string[] required

The list of checks that are pending for the pull request.

check string[] required

The list of checks for that pull request.

check-stale string[] required

The list of checks that are stale for the pull request.

commits-unverified string[] required

The list of commit messages that are marked as unverified by GitHub.

deployment-success string[] required

The list of deployments that successfully passed for the pull request.

deployment-failure string[] required

The list of deployments that failed for the pull request.

review-threads-resolved string[] required

The list of ids associated to review threads that are marked as resolved by GitHub.

review-threads-unresolved string[] required

The list of ids associated to review threads that are NOT marked as resolved by GitHub.

files string[] required

The files that are modified, deleted or added by the pull request.

added-files string[] required

The files that are added by the pull request.

modified-files string[] required

The files that are modified by the pull request.

removed-files string[] required

The files that are removed by the pull request.

added-lines string[] required

The lines that are added by the pull request. Only usable as #added-lines for the number of added lines.

modified-lines string[] required

The lines that are modified by the pull request. Only usable as #modified-lines for the number of modified lines.

deleted-lines string[] required

The lines that are deleted by the pull request. Only usable as #deleted-lines for the number of deleted lines.

co-authors CommitAuthor[] required

The list of co-authors on the pull request (excluding merge commits and bots).

commits-behind string[] required

The list of commits between the head of the base branch and the base of the pull request. This can only be used with the length operator as #commits-behind.

depends-on string[] required

The list of dependencies to other pull request in the format owner/repo#prnumber.

dependabot-dependency-name string[] required

The dependency-name value included in the Dependabot commit message.

dependabot-dependency-type string[] required

The dependency-type value included in the Dependabot commit message.

dependabot-update-type string[] required

The update-type value included in the Dependabot commit message.

commits Commit[] required

The list of commits of the pull request. The index 0 is the first commit, while -1 is the last commit.

current-datetime string required

The current date and time.

format=date-time
updated-at string required

The time the pull request was updated at.

format=date-time
created-at string required

The time the pull request was created at.

format=date-time
closed-at string | null required

The time the pull request was closed at.

merged-at string | null required

The time the pull request was merged at.

queued-at string | null required

The time the pull request was queued at for merge.

queue-merge-started-at string | null required

The time the pull request mergeability checks have started at.

schedule string required

The current time will be compared against this schedule to validate this attribute.

sender-permission string required
Values: "none" "read" "triage" "write" "maintain" "admin"
sender string required

The GitHub login of the command author.

updates PullRequestHeadShaHistoryDict[] required

The list of updates done on an opened pull request.

PullRequestHeadShaHistoryDict object
head-sha string required
timestamp string required
PullRequestRuleConditionsModel AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
PullRequestRuleModel object
name string required

The name of the rule. This is used when reporting information about a rule. It's not possible to have two rules with the same name.

conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[] required
maxItems=500
actions object required
18 nested properties
assign AssignActionModel | null
Default: null
backport BackportActionModel | null
Default: null
close CloseActionModel | null
Default: null
comment CommentActionModel | null
Default: null
copy CopyActionModel | null
Default: null
delete_head_branch DeleteHeadBranchActionModel | null
Default: null
dismiss_reviews DismissReviewsActionModel | null
Default: null
edit EditActionModel | null
Default: null
github_actions GhaActionModel | null
Default: null
label LabelActionModel | null
Default: null
merge MergeActionModel | null
Default: null
post_check PostCheckActionModel | null
Default: null
queue QueueActionModel | null
Default: null
rebase RebaseActionModel | null
Default: null
request_reviews RequestReviewsActionModel | null
Default: null
review ReviewActionModel | null
Default: null
squash SquashActionModel | null
Default: null
update UpdateActionModel | null
Default: null
description string | null

A description of the rule.

Default: null
disabled DisabledDict | null

If the rule is disabled, the reason why it's disabled.

Default: null
PullRequestRulesModel PullRequestRuleModel[]
QueueActionModel object
name string | null

The name of the queue rule where the pull request should be added. If no name is set, queue_conditions will be applied instead.

Default: null
QueueRuleMergeConditionsModel AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
QueueRuleModel object
name string required
queue_conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
merge_conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
branch_protection_injection_mode string

Branch protections conditions injection mode to use.

  • queue will inject branch protections conditions as required conditions for queuing and merging pull requests.
  • merge will inject branch protections conditions as required conditions only for merging pull requests.
  • none will disable branch protections. This mode is supported only on queues using a merge_bot_account with admin rights.
Default: "queue"
Values: "queue" "merge" "none"
batch_size integer

The maximum number of pull requests per speculative check in the queue. Must be between 1 and 128.

Default: 1
min=1max=128
batch_max_wait_time string

The maximum amount of time to wait for additional pull requests before processing a batch that hasn't reached batch_size. The timer starts when the first pull request enters the batch. If batch_size is reached before this time expires, the batch processes immediately. This does not enforce a minimum delay between batches.

Default: "30 seconds"
format=duration
allow_inplace_checks boolean

Deprecated: this value is computed automatically. In-place checks are enabled only when:

  • max_parallel_checks == 1
  • every queue has batch_size == 1
  • every queue CI is single-step (no extra merge_conditions; either empty or identical to queue_conditions)
Default: true
checks_timeout string | null

The amount of time the merge queue waits for pending checks to return before dequeueing pull requests. This cannot be less than 60 seconds.

Default: null
max_checks_retries integer

Number of times Mergify will retry failed CI checks before removing the pull request from the queue. On each retry, the draft pull request is recreated to trigger a fresh CI run. This is useful for handling flaky CI. When set to a value greater than 0, in-place checks are disabled and a draft pull request is always created. Set to 0 (default) to disable retries.

Default: 0
min=0
draft_bot_account string | null

Mergify can impersonate a GitHub user to create its draft pull requests. If no draft_bot_account is set, Mergify creates the draft pull request itself. The user account must have already been logged in Mergify dashboard once and have admin, write or maintain permission.

Default: null
queue_branch_merge_method string | null

If set to fast-forward, Mergify will merge the draft pull request instead of merging the original pull request that has been checked. This only works when merge_method is set to merge.

Default: null
queue_branch_prefix string

Prefix for the merge queue branch name

Default: "mergify/merge-queue/"
format=template
allow_queue_branch_edit boolean

When creating a branch for a queue, if the commits of this branch are edited by an entity external to Mergify, Mergify dequeues all pull requests embarked in the branch and report the issue as a failure. If set to true, Mergify will allow such modifications and trust the content of the branch. Make sure only Mergify and your external application are allowed to edit these branches.

Default: false
batch_max_failure_resolution_attempts integer | null

The number of attempts to resolve a batch failure before dequeueing pull requests. By default, Mergify will attempt to resolve a batch failure by splitting the batch multiple times until it finds the root cause of the failure. You can stop this process earlier by limiting the number of resolution attempts. Setting this to 0 will dequeue all the pull requests from a batch when a batch fails.

Default: null
merge_method string | null

Merge method to use. If no value is set, Mergify uses the first authorized method available in the repository configuration.

Default: null
autosquash boolean

This option is relevant only if you do in place checks and if you use the rebase option of the update_method. It will automatically squash your commits beginning by squash!, fixup! or amend!, just like the option with the same name when doing a git rebase.

Default: false
autoqueue boolean

When set to true, automatically add a pull request to the queue when it matches the queue conditions. When false, the pull request must be manually queued.

Default: false
update_method string | null

Method to use to update the pull request with its base branch when the check is done in place. Possible values:

  • merge to merge the base branch into the pull request.
  • rebase to rebase the pull request against its base branch.

When null, defaults to merge except if merge_method is fast-forward then it defaults to rebase.

Default: null
commit_message_template string | null

Template to use as the commit message when using the merge or squash merge method.

Default: null
merge_bot_account string | null

Mergify can impersonate a GitHub user to merge pull requests. If no merge_bot_account is set, Mergify merges the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission.

Default: null
update_bot_account string | null

For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. If no update_bot_account is set, Mergify uses the pull request author instead. The user account must have already been logged in Mergify dashboard once. This option overrides the value defined in the queue rules section of the configuration.

Default: null
QueueRuleModelForDefaults object
queue_conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
merge_conditions AndCondition | OrCondition | NegationCondition | RuleConditionModel[]
maxItems=500
branch_protection_injection_mode string

Branch protections conditions injection mode to use.

  • queue will inject branch protections conditions as required conditions for queuing and merging pull requests.
  • merge will inject branch protections conditions as required conditions only for merging pull requests.
  • none will disable branch protections. This mode is supported only on queues using a merge_bot_account with admin rights.
Default: "queue"
Values: "queue" "merge" "none"
batch_size integer

The maximum number of pull requests per speculative check in the queue. Must be between 1 and 128.

Default: 1
min=1max=128
batch_max_wait_time string

The maximum amount of time to wait for additional pull requests before processing a batch that hasn't reached batch_size. The timer starts when the first pull request enters the batch. If batch_size is reached before this time expires, the batch processes immediately. This does not enforce a minimum delay between batches.

Default: "30 seconds"
format=duration
allow_inplace_checks boolean

Deprecated: this value is computed automatically. In-place checks are enabled only when:

  • max_parallel_checks == 1
  • every queue has batch_size == 1
  • every queue CI is single-step (no extra merge_conditions; either empty or identical to queue_conditions)
Default: true
checks_timeout string | null

The amount of time the merge queue waits for pending checks to return before dequeueing pull requests. This cannot be less than 60 seconds.

Default: null
max_checks_retries integer

Number of times Mergify will retry failed CI checks before removing the pull request from the queue. On each retry, the draft pull request is recreated to trigger a fresh CI run. This is useful for handling flaky CI. When set to a value greater than 0, in-place checks are disabled and a draft pull request is always created. Set to 0 (default) to disable retries.

Default: 0
min=0
draft_bot_account string | null

Mergify can impersonate a GitHub user to create its draft pull requests. If no draft_bot_account is set, Mergify creates the draft pull request itself. The user account must have already been logged in Mergify dashboard once and have admin, write or maintain permission.

Default: null
queue_branch_merge_method string | null

If set to fast-forward, Mergify will merge the draft pull request instead of merging the original pull request that has been checked. This only works when merge_method is set to merge.

Default: null
queue_branch_prefix string

Prefix for the merge queue branch name

Default: "mergify/merge-queue/"
format=template
allow_queue_branch_edit boolean

When creating a branch for a queue, if the commits of this branch are edited by an entity external to Mergify, Mergify dequeues all pull requests embarked in the branch and report the issue as a failure. If set to true, Mergify will allow such modifications and trust the content of the branch. Make sure only Mergify and your external application are allowed to edit these branches.

Default: false
batch_max_failure_resolution_attempts integer | null

The number of attempts to resolve a batch failure before dequeueing pull requests. By default, Mergify will attempt to resolve a batch failure by splitting the batch multiple times until it finds the root cause of the failure. You can stop this process earlier by limiting the number of resolution attempts. Setting this to 0 will dequeue all the pull requests from a batch when a batch fails.

Default: null
merge_method string | null

Merge method to use. If no value is set, Mergify uses the first authorized method available in the repository configuration.

Default: null
autosquash boolean

This option is relevant only if you do in place checks and if you use the rebase option of the update_method. It will automatically squash your commits beginning by squash!, fixup! or amend!, just like the option with the same name when doing a git rebase.

Default: false
autoqueue boolean

When set to true, automatically add a pull request to the queue when it matches the queue conditions. When false, the pull request must be manually queued.

Default: false
update_method string | null

Method to use to update the pull request with its base branch when the check is done in place. Possible values:

  • merge to merge the base branch into the pull request.
  • rebase to rebase the pull request against its base branch.

When null, defaults to merge except if merge_method is fast-forward then it defaults to rebase.

Default: null
commit_message_template string | null

Template to use as the commit message when using the merge or squash merge method.

Default: null
merge_bot_account string | null

Mergify can impersonate a GitHub user to merge pull requests. If no merge_bot_account is set, Mergify merges the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission.

Default: null
update_bot_account string | null

For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. If no update_bot_account is set, Mergify uses the pull request author instead. The user account must have already been logged in Mergify dashboard once. This option overrides the value defined in the queue rules section of the configuration.

Default: null
QueueRulesModel QueueRuleModel[]
RebaseActionModel object
bot_account string | null

To rebase, Mergify needs to impersonate a GitHub user. You can specify the account to use with this option. If no bot_account is set, Mergify picks the pull request author. The user account must have already been logged in Mergify dashboard once.

Warning: Due to security on GitHub side, rebase cannot be performed on pull requests created by bot accounts without explicitly setting the bot_account impersonation option.

Default: null
autosquash boolean

When set to true, commits starting with fixup!, squash! and amend! are squashed during the rebase.

Default: false
RequestReviewsActionModel object
bot_account string | null

Mergify can impersonate a GitHub user to request a review on a pull request. If no bot_account is set, Mergify will request the review itself.

Default: null
random_count integer | null

Pick random users and teams from the provided lists. When random_count is specified, users and teams can be a dictionary where the key is the login and the value is the weight to use. Weight must be between 1 and 15 included.

Default: null
users string[] | object

The usernames to request reviews from.

teams string[] | object

The team names to request reviews from.

users_from_teams string[] | object

The team names to get the list of users to request reviews from.

ReviewActionModel object
type string

The type of review to post

Default: "APPROVE"
Values: "APPROVE" "REQUEST_CHANGES" "COMMENT"
message string | null

The message to post in the review

Default: null
bot_account string | null

Mergify can impersonate a GitHub user to review a pull request. If no bot_account is set, Mergify will review the pull request itself.

Default: null
RuleConditionModel string

Model defining a single rule condition 'leaf of a condition tree'

Scopes object
source SourceFiles | SourceManual | null

Where scopes come from. files uses file-pattern rules (gha-mergify-ci-scopes must have been setup on your pull request); manual uses scopes sent via API or mergify scopes-send; None disables scoping.

Default: null
merge_queue_scope string

Scope name automatically applied to merge queue PRs.

Default: "merge-queue"
minLength=2pattern=^[A-Za-z0-9_-]+$
SourceFiles object
files object required

Mapping of scope name to its file filters. A file belongs to a scope if it matches the scope's include patterns and not its exclude patterns.

SourceManual object
manual null required

Scopes are manually sent via API or mergify scopes-send

SquashActionModel object
bot_account string | null

Mergify can impersonate a GitHub user to squash a pull request. If no bot_account is set, Mergify will squash the pull request itself

Default: null
commit_message string

Defines what commit message to use for the squashed commit if no commit message is defined in the pull request body. Possible values are:

  • all-commits to use the same format as GitHub squashed merge commit.
  • first-commit to use the message of the first commit of the pull request.
  • title+body means to use the title and body from the pull request itself as the commit message. The pull request number will be added to end of the title.
Default: "all-commits"
Values: "all-commits" "first-commit" "title+body"
UpdateActionModel object
bot_account string | null

Mergify can impersonate a GitHub user to update a pull request. If no bot_account is set, Mergify will update the pull request itself.

Default: null