### Install Dependencies
Source: https://github.com/mergeability/mergeable/blob/master/CONTRIBUTING.md
Run this command to install all necessary project dependencies.
```bash
npm install
```
--------------------------------
### Full Mergeable Recipe Example
Source: https://github.com/mergeability/mergeable/blob/master/docs/configuration.md
This example demonstrates the complete structure of a Mergeable recipe, including event triggers, naming, filtering, validation, and actions for passing, failing, or error states. Use this as a template for your own configurations.
```yaml
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}}
```
--------------------------------
### BeginsWith Validator Example
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/begins_with.md
This snippet demonstrates how to use the begins_with validator for a milestone. The 'match' parameter specifies the required prefix, and 'message' provides a custom error if the validation fails.
```yaml
- do: milestone
begins_with:
match: 'A String' # array of strings
message: 'Some message...'
```
--------------------------------
### BaseRef with Groot Preview Enabled
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/baseRef.md
Example of BaseRef configuration enabling Groot preview for status events on older GitHub Enterprise servers, restricting merges to default branches.
```yaml
- do: baseRef
must_include:
regex: 'master|main'
message: 'Auto-merging is only enabled for default branch'
mediaType:
previews:
- groot
```
--------------------------------
### Assignee Min Validator Example
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/min.md
This snippet demonstrates how to use the 'min' validator to ensure there are at least 2 assignees. An optional custom message can be provided.
```yaml
- do: assignee
min:
count: 2 # There should be more than 2 assignees
message: 'test string' # this is optional
```
--------------------------------
### Nested AND and OR BaseRef Filters
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/baseRef.md
Demonstrates nesting 'and' and 'or' operators to create intricate filtering logic. This example combines a group of 'or' conditions with a single 'must_exclude' condition.
```yaml
- do: baseRef
and:
- or:
- must_include:
regex: 'some-ref'
message: 'Custom message...'
- must_include:
regex: 'some-other-ref'
message: 'Custom message...'
- must_exclude:
regex: 'yet-another-ref'
message: 'Custom message...'
```
--------------------------------
### HeadRef Validator with Include Regex
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/headRef.md
A simple example of the HeadRef validator using a regex to include branches that start with 'feature/' or 'hotfix/'.
```yaml
- do: headRef
must_include:
regex: '^(feature|hotfix)\/.*$'
message: |
Your pull request doesn\'t adhere to the branch naming convention described there!k
```
--------------------------------
### Simple BaseRef Exclusion Example
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/baseRef.md
A basic example of the BaseRef validator that forbids merging into the 'master' branch.
```yaml
- do: baseRef
must_exclude:
regex: 'master'
message: 'Merging into repo:master is forbidden'
```
--------------------------------
### BaseRef Filter with AND and OR Logic
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/baseRef.md
Combine conditions using 'and' and 'or' for more complex filtering rules. This example requires excluding one pattern while including at least one of two others.
```yaml
- do: baseRef
and:
- must_exclude:
regex: 'some-other-ref'
message: 'Custom message...'
or:
- must_include:
regex: 'some-ref'
message: 'Custom message...'
- must_include:
regex: 'some-other-ref'
message: 'Custom message...'
```
--------------------------------
### Nested Not Operator with Or and And
Source: https://github.com/mergeability/mergeable/blob/master/docs/operators/not.md
This example shows nested 'Not' operators combined with 'Or' and 'And' for advanced filtering and validation logic. It excludes merge requests from specific authors if they don't have a 'Ready to Merge' label and their title doesn't start with 'feat:' and include the 'feature' label.
```yaml
filter:
- do: not
filter:
- do: or
filter:
- do: author
must_include: 'user-1'
- do: author
must_include: 'user-2'
validate:
- do: and
validate:
- do: not
validate:
- do: title
begins_with: 'feat:'
- do: label
must_include: 'feature'
- do: label
must_include: 'Ready to Merge'
```
--------------------------------
### Simple LastComment Validation
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/lastComment.md
A basic example to check if the last comment contains only the exact word 'merge'. This is useful for simple keyword checks.
```yaml
# check if the last comment contains only the word 'merge'
- do: lastComment
must_include:
regex: '^merge$'
```
--------------------------------
### Complex LastComment Validation with Author and Logic
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/lastComment.md
This complex example validates the last comment, excluding comments from the PR/Issue author and specific bots. It uses 'or' and 'and' logic to combine multiple conditions for inclusion and exclusion of text.
```yaml
# check if the last comment, not posted by PR/Issue author, meets one of these conditions
# it might have been posted by a bot, except Mergeble itself
- do: lastComment
comment_author:
none_of: ['Mergeable[bot]', '@author']
no_bots: false
or:
- and:
- must_exclude:
regex: 'block|wip|stale'
message: 'pre-requisites are not fulfilled...'
- must_include:
regex: 'agreed|confirmed|compliant'
message: 'pre-requisites are fulfilled...'
- must_include:
regex: '^/override$'
message: 'skip pre-requisite check...'
```
--------------------------------
### Boolean Validation Example
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/boolean.md
This snippet demonstrates how to validate if a pull request draft is exactly false. It uses the 'boolean' type with a 'match' parameter set to false. An optional custom message can be provided.
```yaml
- do: payload
pull_request:
draft:
boolean:
match: false
message: 'Custom message...' # this is optional, a default message is used when not specified.
```
--------------------------------
### Application URL with Ingress Enabled
Source: https://github.com/mergeability/mergeable/blob/master/helm/mergeable/templates/NOTES.txt
If Ingress is enabled, this snippet shows how to construct the application URL using configured hosts and paths. It iterates through defined ingress hosts and their associated paths.
```go-template
{{- if .Values.ingress.enabled }}
{{- range $host := .Values.ingress.hosts }}
{{- range .paths }}
http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ . }}
{{- end }}
{{- end }}
{{- end }}
```
--------------------------------
### Accessing Application with ClusterIP Service
Source: https://github.com/mergeability/mergeable/blob/master/helm/mergeable/templates/NOTES.txt
When using a ClusterIP service, this command finds the pod name and then sets up port forwarding to access the application locally via `http://127.0.0.1:8080`. It also provides instructions on how to access the application.
```bash
export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "mergeable.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
echo "Visit http://127.0.0.1:8080 to use your application"
kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:80
```
--------------------------------
### Application URL with LoadBalancer Service
Source: https://github.com/mergeability/mergeable/blob/master/helm/mergeable/templates/NOTES.txt
For LoadBalancer services, this snippet explains that it may take time for the LoadBalancer IP to become available and provides a command to watch the service status. It then retrieves the service IP and constructs the application URL.
```bash
NOTE: It may take a few minutes for the LoadBalancer IP to be available.
You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "mergeable.fullname" . }}'
export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "mergeable.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}})
echo http://$SERVICE_IP:{{ .Values.service.port }}
```
--------------------------------
### Run Tests and Linter
Source: https://github.com/mergeability/mergeable/blob/master/CONTRIBUTING.md
Execute tests to ensure code quality and functionality. This command also runs the linter.
```bash
npm test
```
--------------------------------
### EndsWith Validation Example
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/ends_with.md
This snippet demonstrates how to use the ends_with validator to check if a 'milestone' attribute ends with the string 'A String'. If it does not, a custom 'Some message...' is displayed.
```yaml
- do: milestone
ends_with:
match: 'A String' # array of strings
message: 'Some message...'
```
--------------------------------
### Available Annotations
Source: https://github.com/mergeability/mergeable/blob/master/docs/annotations.md
Lists the available annotations that can be used to insert dynamic values into recipes. These include author, sender, bot, repository, and action.
```default
@author : replaced with the login of creator of issues/PR
@sender : replaced with the login of initiator of the ocurred event
@bot : replaced with the name of the Mergeable bot
@repository : replaced with the name of repository of issues/PR
@action : replaced with action of the ocurred event
```
--------------------------------
### Create a New Branch
Source: https://github.com/mergeability/mergeable/blob/master/CONTRIBUTING.md
Use this command to create a new branch for your changes.
```bash
git checkout -b my-branch-name
```
--------------------------------
### Nested AND/OR Repository Topic Filters
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/repository.md
Demonstrates nesting 'and' and 'or' conditions within repository topic filters for complex logical combinations. This allows for highly specific topic matching.
```yaml
- do: repository
topics:
and:
- or:
- must_include:
regex: 'topic-1'
message: 'Custom message...'
- must_include:
regex: 'topic-2'
message: 'Custom message...'
- must_include:
regex: 'topic-3'
message: 'Custom message...'
```
--------------------------------
### Validate Dependent Files in Pull Requests
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
This configuration ensures that related files are updated when a specific file is changed. For example, if 'package.json' is updated, 'package-lock.json' and 'yarn.lock' must also be updated.
```yaml
version: 2
mergeable:
- when: pull_request.*
validate:
- do: dependent
changed:
file: 'package.json' # also supports globs expressions
required: ['package-lock.json', 'yarn.lock'] # alias: `files` for backward compatibility
```
--------------------------------
### Application URL with NodePort Service
Source: https://github.com/mergeability/mergeable/blob/master/helm/mergeable/templates/NOTES.txt
When the service type is NodePort, this command retrieves the NodePort assigned to the service and the IP address of a node. It then constructs the application URL using these values.
```bash
export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "mergeable.fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```
--------------------------------
### Comment on Issue Guideline Violations
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
Automatically comments on newly opened issues if the title does not start with a required prefix or if a required label is missing. This helps enforce issue reporting conventions.
```default
version: 2
mergeable:
- when: issues.opened
validate:
- do: title
begins_with:
match: ['AUTH', 'SOCIAL', 'CORE']
- do: label
must_include:
regex: bug|enhancement
fail:
- do: comment
payload:
body: >
The following problems were found with this issue:
- Title must begin with `AUTH`, `SOCIAL` or `CORE`
- The issue should either be labeled `bug` or `enhancement`
```
--------------------------------
### Basic Repository Filter
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/repository.md
Filters repositories based on visibility, name inclusion/exclusion, and topic inclusion/exclusion. Use 'public' or 'private' for visibility.
```yaml
- do: repository
visibility: 'public' # Can be public or private
name:
must_include:
regex: 'my-repo-name'
must_exclude:
regex: 'other-repo-name'
topics:
must_include:
regex: 'my-topic'
message: 'Custom message...'
must_exclude:
regex: 'other-topic'
message: 'Custom message...'
# all of the message sub-option is optional
```
--------------------------------
### Request Review with Reviewers and Teams
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/request_review.md
Use this action to request reviews from specific users and teams. Ensure team names are provided without the organization prefix.
```yaml
- do: request_review
reviewers: ['name1', 'name2']
teams: ['developers'] # team names without organization
```
--------------------------------
### Enforce Commit Message with Issue ID
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
This configuration checks that all commit messages in a pull request start with a specific issue ID format (e.g., 'AB#1234'). It runs on pull request events. If validation passes, it adds a 'Ready for Review' label and comments. If it fails, it adds a 'Non-Compliant' label, comments with instructions, and closes the pull request.
```default
version: 2
mergeable:
- when: pull_request.*
validate:
- do: commit
message:
regex: '^(AB#[0-9]{1,})' #check if all commit messages begin with an AzDO Work Item
pass:
- do: comment
payload:
body: >
Successfully checked for Azure Work Item IDs in commits
All commits in your PR have Azure Board Work Item IDs. Ready for Review!
:+
- do: labels
add: 'Ready for Review'
fail:
- do: comment
payload:
body: >
:warning:
Azure Boards Work Item IDs missing in commits
Some commits messages were found not having the Azure Boards Work Item ID (AB#1234).
We will close this PR for now.
To resolve, please do one of the following
- Identify your Azure Boards Work Item ID and amend your commits. Then re-open the PR
- In case you do not have a Work Item ID to reference, please discuss with your reviewer(s) for alternate options
- do: labels
add: 'Non-Compliant'
- do: close
```
--------------------------------
### Basic And Filter and Validation
Source: https://github.com/mergeability/mergeable/blob/master/docs/operators/and.md
Demonstrates the basic usage of the 'And' operator for both filtering and validation with simple conditions.
```yaml
filter:
- do: and
filter:
- do: author
must_include: 'user-1'
- do: repository
visibility: public
validate:
- do: and
validate:
- do: title
begins_with: '[WIP]'
- do: label
must_include: 'Ready to Merge'
```
--------------------------------
### Combining Description Validators with AND/OR
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/description.md
Demonstrates how to use 'and' and 'or' operators to create complex validation logic for pull request descriptions, allowing for multiple conditions to be met or alternative conditions to be satisfied.
```yaml
- do: description
and:
- must_include:
regex: '### Goals'
message: 'Custom message...'
- must_include:
regex: '### Changes'
message: 'Custom message...'
or:
- must_include:
regex: '### Bug Description'
message: 'Custom message...'
- must_include:
regex: '### Feature Description'
message: 'Custom message...'
```
--------------------------------
### Supported Actions for Annotations
Source: https://github.com/mergeability/mergeable/blob/master/docs/annotations.md
Specifies the actions for which annotations can be used. These are assign, comment, and checks.
```default
'assign', 'comment', 'checks'
```
--------------------------------
### Size Validation with File Matching and Ignoring
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/size.md
Configure the size validator to include or exclude specific files and directories using glob patterns. The `match` setting filters files first, followed by the `ignore` setting.
```yaml
- do: size
match: ['src']
ignore: ['package-lock.json', 'src/tests/__snapshots__/**', 'docs/*.md']
lines:
total:
count: 500
message: Change is very large. Should be under 500 lines of additions and deletions
```
--------------------------------
### Supported Events for Close Action
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/close.md
Lists the events that can trigger the 'close' action. Ensure your workflow is configured to listen for these events.
```yaml
'schedule.repository',
'pull_request.*',
'issues.*',
'issue_comment.*'
```
--------------------------------
### Basic Change Set Validation Configuration
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/changeset.md
Configure basic changeset validation rules including emptiness, inclusion, exclusion, prefix, suffix, and file count limits. Custom messages can be provided for each rule.
```yaml
- do: changeset # validate against the files in the PR
no_empty:
enabled: false # Cannot be empty when true.
message: 'Custom message...'
must_include:
regex: 'yarn.lock'
message: 'Custom message...'
must_exclude:
regex: 'package.json'
message: 'Custom message...'
begins_with:
match: 'A String' # or array of strings
message: 'Some message...'
ends_with:
match: 'A String' # or array of strings
message: 'Come message...'
min:
count: 2 # min number of files in a PR
message: 'Custom message...'
max:
count: 2 # max number of files in a PR
message: 'Custom message...'
files: # status of files to be included in changeset. If no 'files' option is provided, all files are included.
added: true # default: false. If true, added files are included.
modified: false # default: false. If true, modified files are included.
removed: true # default: false. If true, deleted files are included.
# note that setting file status sub-options (added, modified, removed) to false is optional.
# all of the message sub-option is optional
```
--------------------------------
### Basic Or Filter and Validate
Source: https://github.com/mergeability/mergeable/blob/master/docs/operators/or.md
Demonstrates the basic usage of the 'Or' operator for both filtering and validation. Use this when any one of the sub-conditions should satisfy the check.
```yaml
filter:
- do: or
filter:
- do: author
must_include: 'user-1'
- do: repository
visibility: public
validate:
- do: or
validate:
- do: title
begins_with: '[WIP]'
- do: label
must_include: 'Ready to Merge'
```
--------------------------------
### Nested Or with And
Source: https://github.com/mergeability/mergeable/blob/master/docs/operators/or.md
Shows how to create nested 'Or' conditions within an 'And' operator for more complex filtering and validation scenarios. This is useful for defining intricate logical requirements.
```yaml
filter:
- do: and
filter:
- do: or
filter:
- do: author
must_include: 'user-1'
- do: author
must_include: 'user-2'
- do: repository
visibility: public
validate:
- do: and
validate:
- do: or
validate:
- do: title
begins_with: '[WIP]'
- do: label
must_include: '[WIP]'
- do: label
must_include: 'DO NOT MERGE'
```
--------------------------------
### Approval Configuration Rules
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/approval.md
Configure minimum required approvals, specific reviewers, blocking conditions, and limiting/excluding users or teams for pull request reviews.
```yaml
- do: approvals
min:
count: 2 # Number of minimum reviewers. In this case 2.
message: 'Custom message...'
required:
reviewers: [ user1, user2 ] # list of github usernames required to review
owners: true # Optional boolean. When true, the file .github/CODEOWNERS is read and owners made required reviewers
assignees: true # Optional boolean. When true, PR assignees are made required reviewers.
requested_reviewers: true # Optional boolean. When true, all the requested reviewer's approval is required
message: 'Custom message...'
block:
changes_requested: true # If true, block all approvals when one of the reviewers gave 'changes_requested' review
message: 'Custom message...'
limit:
teams: ['org/team_slug'] # when the option is present, only the approvals from the team members will count
users: ['user1', 'user2'] # when the option is present, approvals from users in this list will count
owners: true # Optional boolean. When true, the file .github/CODEOWNER is read and only owners approval will count
exclude:
users: ['bot1', 'bot2'] # when the option is present, approvals from users in this list will NOT count
```
--------------------------------
### Basic Required Approvals Configuration
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/required.md
This snippet shows how to configure the 'required' option for approvals, specifying a list of required reviewers and enabling checks for file owners and assignees. It also includes a custom failure message.
```yaml
- do: approvals
required:
reviewers: [ user1, user2 ] # list of github usernames required to review
owners: true # Optional boolean. When true, the file .github/CODEOWNERS is read and owners made required reviewers
assignees: true # Optional boolean. When true, PR assignees are made required reviewers.
requested_reviewers: true # Optional boolean. When true, all the requested reviewer's approval is required
message: 'Custom message...'
```
--------------------------------
### Supported Events for Repository Filters
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/repository.md
Lists the events that can trigger repository-related mergeability checks. These include pull request and review events.
```text
'pull_request.*', 'pull_request_review.*'
```
--------------------------------
### Payload Matching Options
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/payload.md
This snippet outlines the available options for matching fields within an event payload, including boolean, regex inclusion/exclusion, and list comparisons.
```yaml
boolean:
match: true/false
must_include:
regex: 'This text must be included'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
key: 'name' # Optional. If checking an array of objects, this specifies the key to check.
must_exclude:
regex: 'Text to exclude'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
key: 'name' # Optional. If checking an array of objects, this specifies the key to check.
one_of: ['user-1', 'user-2'] # Compares the field value for occurance in the list of strings, case-insensitive, annotations supported
none_of: ['@author', '@bot'] # Compares the field value for absence in the list of strings, case-insensitive, annotations supported
```
--------------------------------
### Nested AND/OR Author Filters
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/author.md
Nest 'and' and 'or' conditions to create sophisticated author filtering logic.
```yaml
- do: author
and:
- or:
- must_include:
regex: 'user-1'
message: 'Custom message...'
- must_include:
regex: 'user-2'
message: 'Custom message...'
- must_exclude:
regex: 'bot-user-1'
message: 'Custom message...'
```
--------------------------------
### Enable NoEmpty Validation
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/no_empty.md
This snippet shows how to configure the 'no_empty' option. Set 'enabled' to 'false' to disable it. A custom 'message' can be provided for validation failures.
```yaml
- do: description
no_empty:
enabled: false # Cannot be empty when true.
message: 'Custom message...' # this is optional, a default message is used when not specified.
```
--------------------------------
### Label Validator Basic Options
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/label.md
Configure basic label validation rules like emptiness, inclusion, exclusion, and format.
```yaml
- do: label
no_empty:
enabled: false # Cannot be empty when true.
message: 'Custom message...'
must_include:
regex: 'type|chore|wont'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
must_exclude:
regex: 'DO NOT MERGE'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
begins_with:
match: 'A String' # or array of strings
message: 'Some message...'
ends_with:
match: 'A String' # or array of strings
message: 'Come message...'
jira:
regex: '[A-Z][A-Z0-9]+-\d+'
regex_flag: none
message: 'The Jira ticket does not exist'
# all of the message sub-option is optional
```
--------------------------------
### Reusable Comment Configuration with YAML Anchor
Source: https://github.com/mergeability/mergeable/blob/master/docs/configuration.md
This snippet shows how to define a reusable comment action using a YAML anchor (&default_fail_comment). This anchor can then be referenced in multiple validation rules to apply the same failure comment.
```yaml
on_fail_comment: &default_fail_comment
- do: comment
payload:
body: >
This issue fails to meet the guidelines, please check the contribution guideline and make sure all the necessary items are in place.
version: 2
mergeable:
- when: pull_request.*
validate:
- do: approvals
min:
count: 1
- do: labels
fail:
- <<: *default_fail_comment
- do: assign
assignees: ['@author']
- when: issues.*
validate:
- do: description
no_empty:
enabled: true
fail: *default_fail_comment
```
--------------------------------
### Complex Repository Filter with AND/OR Topics
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/repository.md
Combines topic filters using 'and' and 'or' logic for more granular control. Each condition within 'and' or 'or' must be met.
```yaml
- do: repository
topics:
and:
- must_include:
regex: 'topic-1'
message: 'Custom message...'
- must_include:
regex: 'topic-2'
message: 'Custom message...'
or:
- must_include:
regex: 'topic-3'
message: 'Custom message...'
- must_include:
regex: 'topic-4'
message: 'Custom message...'
```
--------------------------------
### Close Action
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/close.md
This snippet shows the basic syntax for the 'close' action. Use this to programmatically close a pull request or issue.
```yaml
- do: close
```
--------------------------------
### Nested AND/OR Description Validators
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/description.md
Illustrates advanced configuration of description validators using nested 'and' and 'or' logic, enabling sophisticated rule sets for pull request descriptions.
```yaml
- do: description
and:
- or:
- must_include:
regex: '### Bug Description'
message: 'Custom message...'
- must_include:
regex: '### Feature Description'
message: 'Custom message...'
- must_include:
regex: '### Changes'
message: 'Custom message...'
```
--------------------------------
### Approval and Title Check for Specific Files
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
This configuration adds two checks: one for approvals by specific users and another for PR title format if certain files are modified. The title check passes if the specified files are not changed or if they are changed and the title matches the required prefix.
```yaml
version: 2
mergeable:
- when: pull_request.*, pull_request_review.*
name: 'Approval check'
validate:
- do: approvals
min:
count: 1
limit:
users: [ 'approverA', 'approverB' ]
- when: pull_request.*, pull_request_review.*
name: 'PR title check'
validate:
- do: or
validate:
- do: changeset
must_exclude:
regex: 'some/regex/for/those/certain/files/*'
- do: and
validate:
- do: changeset
must_include:
regex: 'some/regex/for/those/certain/files/*'
- do: title
begins_with:
match: [ 'some prefix' ]
```
--------------------------------
### Nested And with Or Filter and Validation
Source: https://github.com/mergeability/mergeable/blob/master/docs/operators/and.md
Shows how to create nested 'And' operators combined with 'Or' operators for more complex filtering and validation logic.
```yaml
filter:
- do: and
filter:
- do: or
filter:
- do: author
must_include: 'user-1'
- do: author
must_include: 'user-2'
- do: repository
visibility: public
validate:
- do: and
validate:
- do: or
validate:
- do: title
begins_with: 'feat:'
- do: label
must_include: 'feature'
- do: label
must_include: 'Ready to Merge'
```
--------------------------------
### Supported Events for Comment Action
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/comment.md
This snippet lists the events that can trigger the comment action. Ensure your workflow is configured to listen to these events.
```YAML
'schedule.repository', 'pull_request.*', 'issues.*', 'issue_comment.*'
```
--------------------------------
### Supported Events for Assignee Validator
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/assignee.md
Lists the events that trigger the Assignee validator. This includes various pull request, review, and issue-related events.
```string
'pull_request.*', 'pull_request_review.*', 'issues.*', 'issue_comment.*'
```
--------------------------------
### Project Validator Configuration
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/project.md
Configure the 'project' validator to enforce specific patterns in pull request descriptions. Use 'must_include' with a regex to define required keywords.
```yaml
- do: project
must_include:
regex: 'type|chore|wont'
message: 'Custom message...'
```
--------------------------------
### Greet New Contributors on Pull Request
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
Adds a comment to a pull request when it is opened. This is useful for acknowledging new contributors and informing them about the review process.
```default
version: 2
mergeable:
- when: pull_request.opened
name: "Greet a contributor"
validate: []
pass:
- do: comment
payload:
body: >
Thanks for creating a pull request! A maintainer will review your changes shortly. Please don't be discouraged if it takes a while.
```
--------------------------------
### Supported Events for Request Review
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/request_review.md
This action is triggered by pull request events. The wildcard 'pull_request.*' covers all pull request related events.
```yaml
'pull_request.*'
```
--------------------------------
### Label Validator Nested AND/OR Logic
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/label.md
Demonstrates nesting AND and OR conditions for advanced label validation scenarios.
```yaml
- do: label
and:
- or:
- must_include:
regex: 'feat|fix|chore'
message: 'Custom message...'
- must_include:
regex: 'major|minor|patch'
message: 'Custom message...'
- must_include:
regex: 'Ready to merge'
message: 'Custom message...'
```
--------------------------------
### Size Validation with Total, Additions, and Deletions
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/size.md
Configure the size validator to enforce limits on total lines, additions, and deletions. The `ignore_comments` option can be set to `false` to include comments in the line count.
```yaml
- do: size
lines:
total:
count: 500
message: Change is very large. Should be under 500 lines of additions and deletions.
additions:
count: 250
message: Change is very large. Should be under 250 lines of additions
deletions:
count: 250
message: Change is very large. Should be under 250 lines of deletions.
ignore_comments: false #if true, comments will not be counted toward the lines count
```
--------------------------------
### Enforce Non-Empty Pull Request Descriptions
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
This configuration ensures that all pull requests have a description. It validates that the description is not empty and provides a custom message if it is.
```yaml
version: 2
mergeable:
- when: pull_request.*
validate:
- do: description
no_empty:
enabled: true
message: Description matter and should not be empty. Provide detail with **what** was changed, **why** it was changed, and **how** it was changed.
```
--------------------------------
### Supported Events for Merge Action
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/merge.md
This action can be triggered by various events related to pull requests, statuses, and check suites.
```yaml
'pull_request.*', 'pull_request_review.*', 'status.*', 'check_suite.*', 'issue_comment.*'
```
--------------------------------
### Basic Title Validation Rules
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/title.md
Configure basic title validation rules like checking for emptiness, required inclusions, exclusions, and specific start/end patterns. Use this for standard commit message formatting.
```yaml
- do: title
no_empty:
enabled: true # Cannot be empty when true. A bit redundant in this case since GitHub don't really allow it. :-)
message: 'Custom message...'
must_include:
regex: 'doc|feat|fix|chore'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
must_exclude:
regex: 'DO NOT MERGE|WIP'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
begins_with:
match: ['doc','feat','fix','chore']
message: 'Some message...'
ends_with:
match: 'A String' # or array of strings
message: 'Come message...'
# all of the message sub-option is optional
jira:
regex: '[A-Z][A-Z0-9]+-\d+'
regex_flag: none
message: 'The Jira ticket does not exist'
```
--------------------------------
### Replace All Labels
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/labels.md
Replaces all current labels on an item with a new set of labels. Use this when you want to enforce a specific set of labels.
```yaml
- do: labels
replace: [ 'Triage', 'Needs Deploy' ]
```
--------------------------------
### Combine Label Operations
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/labels.md
Combines replace, add, and delete operations in a single action. The operations are evaluated in the order: replace, add, then delete.
```yaml
- do: labels
replace: [ 'New Task', 'Not Useful' ]
add: [ 'Work in Progress', 'Needs Deploy' ]
delete: 'Not Useful'
# result: [ 'New Task', 'Work in Progress', 'Needs Deploy' ]
```
--------------------------------
### Configure File Content Validation
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/contents.md
Define rules for validating file contents, such as inclusion, exclusion, and format checks. Use 'pr_diff: true' to validate all changed files in the PR.
```yaml
- do: contents
files: # determine which files contents to validate
pr_diff: true # If true, validator will grab all the added and modified files in the head of the PR
ignore: ['.github/mergeable.yml'] # Optional, default ['.github/mergeable.yml'], pattern of files to ignore
must_include:
regex: 'yarn.lock'
message: 'Custom message...'
must_exclude:
regex: 'package.json'
message: 'Custom message...'
begins_with:
match: 'A String' # or array of strings
message: 'Some message...'
ends_with:
match: 'A String' # or array of strings
message: 'Come message...'
```
--------------------------------
### Detect and Comment on Stale PRs and Issues
Source: https://github.com/mergeability/mergeable/blob/master/docs/recipes.md
Identifies issues and pull requests that have not been updated for a specified number of days and notifies the author by creating a comment. This helps in cleaning up old, inactive items.
```default
version: 2
mergeable:
- when: schedule.repository
validate:
- do: stale
days: 20
type: pull_request, issues
pass:
- do: comment
payload:
body: This is old. Is it still relevant?
```
--------------------------------
### Basic Author Filters
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/author.md
Use these filters to specify inclusion, exclusion, team membership, or specific user/team requirements for pull request authors.
```yaml
- do: author
must_include:
regex: 'user-1'
message: 'Custom include message...' # optional
must_exclude:
regex: 'user-2'
message: 'Custom exclude message...' # optional
team: 'org/team-slug' # verify that the author is in the team
one_of: ['user-1', '@org/team-slug'] # verify author for being one of the users or a team member
none_of: ['user-2', '@bot'] # verify author for not being one of the users or the mergeable bot
```
--------------------------------
### Milestone Validator Basic Configuration
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/milestone.md
Configure basic milestone validation rules such as ensuring the title is not empty, must include specific patterns, must exclude certain patterns, begins with, or ends with specific strings. The 'message' sub-option is optional for most rules.
```yaml
- do: milestone
no_empty:
enabled: true # Cannot be empty when true.
message: 'Custom message...'
must_include:
regex: 'type|chore|wont'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
must_exclude:
regex: 'DO NOT MERGE'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
begins_with:
match: 'A String' # array of strings
message: 'Some message...'
ends_with:
match: 'A String' # array list of strings
message: 'Come message...'
jira:
regex: '[A-Z][A-Z0-9]+-\d+'
regex_flag: none
message: 'The Jira ticket does not exist'
# all of the message sub-option is optional
```
--------------------------------
### Milestone Validator AND/OR Conditions
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/milestone.md
Configure complex milestone validation by combining multiple conditions using 'and' and 'or' operators. This allows for more granular control over pull request title and description requirements.
```yaml
- do: milestone
and:
- must_include:
regex: 'V1'
message: 'Custom message...'
- must_include:
regex: 'October'
message: 'Custom message...'
or:
- must_include:
regex: 'V2'
message: 'Custom message...'
- must_include:
regex: 'Non breaking Changes'
message: 'Custom message...'
```
--------------------------------
### BaseRef Validator Configuration
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/baseRef.md
Configure the BaseRef validator to include or exclude specific branches using regex. Includes optional regex flags and custom messages. Media type for Groot preview is also shown.
```yaml
- do: baseRef
must_include:
regex: 'master|feature-branch1'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
must_exclude:
regex: 'feature-branch2'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
mediaType: # Optional. Required by status.* events to enable the groot preview on some Github Enterprise servers
previews: 'array'
```
--------------------------------
### Supported Events for Project Validation
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/project.md
Specifies the events that trigger the project validator. This includes pull request, pull request review, and issue events.
```yaml
'pull_request.*', 'pull_request_review.*', 'issues.*'
```
--------------------------------
### Complex Author Filters with AND/OR
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/author.md
Combine multiple author conditions using 'and' and 'or' for more granular control over mergeability.
```yaml
- do: author
and:
- must_exclude:
regex: 'bot-user-1'
message: 'Custom message...'
or:
- must_include:
regex: 'user-1'
message: 'Custom message...'
- must_include:
regex: 'user-2'
message: 'Custom message...'
```
--------------------------------
### Add Labels with Deprecated Mode
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/labels.md
Adds a set of labels to an item using the deprecated `mode: 'add'` option. If a label does not exist, it will be created. This method is deprecated in favor of the `add` option.
```yaml
- do: labels
# if label doesn't exist, it'll be created
labels: [ 'Triage' ] # Only arrays are accepted
mode: 'add' # Optional , default is 'add'. Other options : 'replace', 'delete'
```
--------------------------------
### HeadRef Validator Configuration
Source: https://github.com/mergeability/mergeable/blob/master/docs/validators/headRef.md
Configure the HeadRef validator with inclusion, exclusion, and Jira ticket regex patterns. Use 'regex_flag: "none"' to disable default case-insensitivity.
```yaml
- do: headRef
must_include:
regex: 'feature-branch1'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
must_exclude:
regex: 'feature-branch2'
regex_flag: 'none' # Optional. Specify the flag for Regex. default is 'i', to disable default use 'none'
message: 'Custom message...'
jira:
regex: '[A-Z][A-Z0-9]+-\d+'
regex_flag: none
message: 'The Jira ticket does not exist'
```
--------------------------------
### Simple BaseRef Filter with Must Include
Source: https://github.com/mergeability/mergeable/blob/master/docs/filters/baseRef.md
Use this filter to ensure a branch name includes a specific regex pattern. The 'message' field provides a custom error message.
```yaml
- do: baseRef
must_include:
regex: 'some-ref'
message: 'Custom message...'
# all of the message sub-option is optional
```
--------------------------------
### Replace Labels with Deprecated Mode
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/labels.md
Replaces all existing labels with a new set using the deprecated `mode: 'replace'` option. If a label does not exist, it will be created. This method is deprecated in favor of the `replace` option.
```yaml
- do: labels
# if label doesn't exist, it'll be created
labels: [ 'Triage' ] # Only arrays are accepted
mode: 'replace' # Replaces all of the labels with the above array of labels
```
--------------------------------
### Supported Validators for Max
Source: https://github.com/mergeability/mergeable/blob/master/docs/options/max.md
Lists the validators that support the 'max' length constraint.
```text
'approvals', 'assignee', 'changeset', 'label'
```
--------------------------------
### Supported Events for Assign Action
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/assign.md
The 'assign' action is triggered by events related to pull requests, issues, and issue comments. Ensure your configuration includes these event types for the action to function.
```yaml
'pull_request.*',
'issues.*',
'issue_comment.*'
```
--------------------------------
### Add a New Label
Source: https://github.com/mergeability/mergeable/blob/master/docs/actions/labels.md
Adds a new label to an item, preserving any existing labels. Use this when you want to append a label without affecting others.
```yaml
- do: labels
add: 'Ready for Review'
```