Skip to main content
The Merge Action allows you to automatically merge pull requests when they pass all validations. This is useful for automating routine merges, reducing manual work, and maintaining a consistent workflow.

​
Configuration

​
method
string
default:"merge"
Merge method to use: “merge”, “squash”, or “rebase”
​
commit_title
string
Custom title for the merge commit (supports templates)
​
commit_message
string
Custom message for the merge commit (supports templates)

​
Basic Usage

on_success:
  - merge:
      method: "squash"

​
Examples

​
Simple Auto-Merge

Automatically merge PRs that pass all validations: 
on_success:
  - merge:
      method: "merge"

​
Custom Commit Messages

Specify custom titles and messages for merge commits: 
on_success:
  - merge:
      method: "squash"
      commit_title: "{{ pull_request.title }} (#{{ pull_request.number }})"
      commit_message: |
        {{ pull_request.body }}
        
        Merged by Rulesets automation.

​
Conditional Auto-Merge

Merge documentation PRs automatically after review: 
ruleset:
  - name: "Auto-merge Documentation Updates"
    when:
      - "pull_request_review.submitted"
    if:
      - type: "files"
        modified:
          match: "^(docs/|README.md|*.md)$"
      - type: "label"
        match: "documentation"
    validate:
      - type: "approvals"
        count:
          min: 1
    on_success:
      - merge:
          method: "squash"
          commit_title: "docs: {{ pull_request.title }}"

​
Merge Methods

  • Merge
  • Squash
  • Rebase
Creates a merge commit that preserves all commit history from the PR branch.
merge:
  method: "merge"
Best for: Preserving detailed history and context of changes.

​
How It Works

1

Check Mergeability

The action first checks if the PR is mergeable
2

Process Templates

If custom commit titles or messages are provided, it processes the templates
3

Perform Merge

The action merges the PR using the specified method

​
Error Handling

The Merge Action will fail under these conditions:
  • PR has merge conflicts
  • PR doesn’t meet branch protection requirements
  • Required status checks are failing
  • User lacks permission to merge
When merge fails, the error will be logged but won’t affect other actions.

​
Use Cases

​
Auto-Merge Dependency Updates

Automatically merge dependency updates that pass tests: 
ruleset:
  - name: "Auto-merge Dependencies"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
      - "check_suite.completed"
    if:
      - type: "author"
        match: ["dependabot", "renovate"]
      - type: "check_suite"
        status: "success"
    validate:
      - type: "size"
        files: 5
        ignore: ["package-lock.json", "yarn.lock"]
    on_success:
      - merge:
          method: "squash"
          commit_title: "chore(deps): {{ pull_request.title }}"

​
Auto-Merge Typo Fixes

Automatically merge simple typo fixes after approval: 
ruleset:
  - name: "Auto-merge Typo Fixes"
    when:
      - "pull_request_review.submitted"
    if:
      - type: "title"
        match: "^fix\\(typo\\): .*"
      - type: "size"
        total: 50
    validate:
      - type: "approvals"
        count:
          min: 1
    on_success:
      - merge:
          method: "squash"

​
Auto-Merge for Specific Labels

Merge PRs with specific labels after CI success: 
ruleset:
  - name: "Auto-merge Labeled PRs"
    when:
      - "check_suite.completed"
      - "pull_request.labeled"
    if:
      - type: "label"
        match: "auto-merge"
      - type: "check_suite"
        status: "success"
    validate:
      - type: "approvals"
        count:
          min: 2
    on_success:
      - merge:
          method: "merge"

​
Best Practices

Use with appropriate validation checks to ensure quality
Consider branch protection rules when setting up auto-merge
Choose the merge method that best fits your workflow
Use custom commit messages to maintain a meaningful history
Be cautious with auto-merge on critical branches - always include sufficient validation

​
Security Considerations

  • Only enable auto-merge for trusted contributors or with strict validation
  • Ensure all required checks (tests, approvals) are passing before merge
  • Consider limiting auto-merge to non-critical repositories or branches
  • Maintain audit logs of auto-merged PRs
⌘I