Configuration¶
Mergeable is highly configurable.
First, you’ll need to start by creating a .github/mergeable.yml
file in your repository.
Hint
Check out our Recipes page for examples and most commonly used settings
Next, we’ll go into how the configuration is structured.
Basics¶
Mergeable configuration consists of an array of independent recipes where each recipe needs to have the following properties:
- when:
- specify webhook event(s) in which to process the validation
- name:
- a friendly name which appears on the PR for the associated check
- filter:
- specify a series of optional filters to be checked and only runs validators if they are passing
- validate:
- specify a series of validator to be checked
- pass:
- specify a series of action to execute if the validation suite returned a pass
- fail:
- specify a series of action to execute if the validation suite returned a fail
- error:
- specify a series of action to execute if the validation suite returned a error
Each recipe appears as a separate check in the pull request.
Here is a full example of how a recipe looks -
version: 2
mergeable:
- when: {{event}}, {{event}} # can be one or more
name: check name A
filter:
# list of filters (optional). Specify one or more.
- do: {{filter}}
{{option}}: # name of an option supported by the validator.
{{sub-option}}: {{value}} # an option will have one or more sub-options.
validate:
# list of validators. Specify one or more.
- do: {{validator}}
{{option}}: # name of an option supported by the validator.
{{sub-option}}: {{value}} # an option will have one or more sub-options.
pass: # list of actions to be executed if all validation passes. Specify one or more. Omit this tag if no actions are needed.
- do: {{action}}
fail: # list of actions to be executed when at least one validation fails. Specify one or more. Omit this tag if no actions are needed.
- do: {{action}}
error: # list of actions to be executed when at least one validator throws an error. Specify one or more. Omit this tag if no actions are needed.
- do: {{action}}
- when: {{event}}, {{event}} # example for second recipe
name: check name B
filter:
# list of filters (optional). Specify one or more.
- do: {{filter}}
{{option}}: # name of an option supported by the validator.
{{sub-option}}: {{value}} # an option will have one or more sub-options.
validate:
# list of validators. Specify one or more.
- do: {{validator}}
{{option}}: # name of an option supported by the validator.
{{sub-option}}: {{value}} # an option will have one or more sub-options.
pass: # list of actions to be executed if all validation passes. Specify one or more. Omit this tag if no actions are needed.
- do: {{action}}
fail: # list of actions to be executed when at least one validation fails. Specify one or more. Omit this tag if no actions are needed.
- do: {{action}}
error: # list of actions to be executed when at least one validator throws an error. Specify one or more. Omit this tag if no actions are needed.
- do: {{action}}
Note
There are some default actions that’ll be automatically applied based on the events specified
Filters¶
Filters are checks that mergeable will process in order to determine if validator will be executed.
Note
Each filter have certain events that it can support, so keep an eye out for them.
Hint
Don’t see an filter that should be on here? Let us know by creating an issue on github
Filter List
Validators¶
Validators are checks that mergeable will process in order to determine whether an action should be executed.
Note
Each validator have certain events that it can support, so keep an eye out for them.
Hint
Don’t see an validator that should be on here? Let us know by creating an issue on github
Validator List
Actions¶
Actions that mergeable is currently able to perform.
Hint
Don’t see an action that should be on here? Let us know by creating an issue on github
Reusable Configuration¶
YML has a feature called `Anchor<https://blog.daemonl.com/2016/02/yaml.html>`_ that allows you to create reusable parts in the config
Organisation-wide defaults¶
You can specify a default configuration to be applied across your GitHub organisation. This can help reduce how many configuration files you need to maintain and make it easier to get started with Mergeable.
To add a default configuration:
- Create a repository called
.github
in your organisation. - Create a file with the path
.github/mergeable.yml
in this repository.
The final path of the file (including the repo name) should be <YOUR_ORG>/.github/.github/mergeable.yml
Mergeable will now use this file as the default when it cannot find one in a given repository or PR. It determines the file to use in the following order:
- A
mergeable.yml
inside the PR if the PR originates from the same repository. If it originates from a fork it is not loaded for security reasons. See #406 for more details. - A
mergeable.yml
inside the repository the PR is for. - A
mergeable.yml
at<YOUR_ORG>/.github/.github/mergeable.yml
.
Note
If config file is changed in base branch, all the PR against the base branch will be re ran using the changed config file
Warning! this feature require mergeable have read
access to contents and needs to be listening for push
event
Why the weird default file path?¶
The Probots library that Mergeable uses automatically searches for config files
in a repo named .github
within the organisation.
The double nesting of the <YOUR_ORG>/.github/.github/mergeable.yml
default
file is unfortunately necessary. The GitHub app permissions model only lets you
specify a single path for your probot to access, so it must be the same as in
regular repositories.