MQL5-Google-Onedrive/docs/Auto_Merge_Guide.md

Auto-Merge Setup and Usage Guide

Overview

This repository is configured with automated merge capabilities to streamline the development workflow. When a pull request has the automerge label, GitHub will automatically merge it once all required checks pass.

How Auto-Merge Works

The auto-merge workflow (.github/workflows/enable-automerge.yml) automatically enables GitHub's auto-merge feature for pull requests that:

1. Have the automerge label
2. Are not in draft status
3. Meet all branch protection requirements

Prerequisites

Repository Settings

Ensure the following settings are configured in GitHub:

1. Enable Auto-Merge Feature

   • Go to Settings → General
   • Scroll to Pull Requests section
   • Check ✓ Allow auto-merge

2. Branch Protection Rules (recommended)

   • Go to Settings → Branches
   • Add rule for main branch:
     • ✓ Require pull request reviews before merging (at least 1)
     • ✓ Require status checks to pass before merging
       • Add required check: CI / validate-and-package
     • ✓ Require branches to be up to date before merging (optional)

Using Auto-Merge

For Pull Request Authors

1. Create a Pull Request

   git checkout -b feature/my-new-feature
   # Make your changes
   git add .
   git commit -m "Add new feature"
   git push origin feature/my-new-feature
   

2. Add the automerge Label

   • Go to your pull request on GitHub
   • Click on Labels in the right sidebar
   • Select or create the automerge label

3. Wait for Checks to Pass

   • The auto-merge workflow will automatically enable GitHub's auto-merge
   • Once all required checks pass and reviews are approved, the PR will be merged automatically
   • The branch will be deleted after merge (if configured)

For This Specific PR

To enable auto-merge for your pull request:

1. Navigate to the pull request in GitHub
2. Add the automerge label
3. Ensure all CI checks pass
4. Get required approvals (if branch protection requires reviews)
5. The PR will automatically merge once all conditions are met

Merge Method

The auto-merge workflow uses squash merge by default. This means:

• All commits in the PR are squashed into a single commit
• The commit message will be the PR title
• The commit description will include all individual commit messages
• Clean, linear commit history on the main branch

Workflow Triggers

The auto-merge workflow runs when:

• A PR is labeled with automerge
• A PR is reopened
• A PR becomes ready for review (no longer draft)
• A PR is synchronized (new commits pushed)

Manual Merge Alternative

If you prefer to merge manually:

1. Don't add the automerge label
2. Use GitHub's merge button when ready
3. Choose your preferred merge method (squash, merge commit, or rebase)

Troubleshooting

Auto-Merge Not Enabled

If auto-merge doesn't enable automatically:

• Check that the PR has the automerge label
• Verify the PR is not in draft status
• Review workflow logs in the Actions tab

Auto-Merge Enabled But Not Merging

If auto-merge is enabled but the PR doesn't merge:

• Check if all required status checks are passing
• Verify you have the required number of approvals
• Ensure the branch is up to date (if required)
• Check for merge conflicts

Workflow Permissions

If you see permission errors:

• The workflow requires contents: write and pull-requests: write permissions
• These are configured in the workflow file
• Contact repository administrators if issues persist

Security Considerations

1. Required Reviews: Always configure branch protection to require reviews for production branches
2. Status Checks: Ensure CI checks are required and passing before merge
3. CODEOWNERS: Consider adding CODEOWNERS file for critical paths
4. Label Permissions: Restrict who can add the automerge label in repository settings

Branch Cleanup

After a successful auto-merge:

• GitHub can automatically delete the source branch
• Enable this in Settings → General → Pull Requests
• Check ✓ Automatically delete head branches

Related Workflows

This repository includes other automated workflows:

• CI: Validates code and packages artifacts
• OneDrive Sync: Syncs MT5 files to OneDrive after merge
• Trading News Monitor: Scheduled monitoring of trading news

Examples

Example 1: Feature Branch with Auto-Merge

# Create feature branch
git checkout -b feature/add-new-indicator
git push origin feature/add-new-indicator

# Create PR on GitHub and add 'automerge' label
# Push commits
git commit -m "Add new indicator"
git push

# PR automatically merges when CI passes and reviews are approved

Example 2: Hotfix with Immediate Merge

# Create hotfix branch
git checkout -b hotfix/fix-critical-bug
git push origin hotfix/fix-critical-bug

# Create PR and add 'automerge' label
# Get emergency approval
# CI passes → Auto-merge triggers → Merged!

Best Practices

1. Use for routine PRs: Auto-merge works well for well-tested, routine changes
2. Review before labeling: Only add automerge after reviewing the changes
3. Monitor CI: Ensure your CI is comprehensive and catches issues
4. Test locally: Run tests locally before pushing to catch issues early
5. Keep PRs small: Smaller PRs are easier to review and merge safely

Reference

• GitHub Auto-Merge Documentation
• Branch Protection Documentation
• Repository Workflow: .github/workflows/enable-automerge.yml