docs: document how to use approve-only with GitHub's automerge

README.md

@@ -26,6 +26,8 @@ _Optional_ An arbitrary message that you'd like to comment on the PR after it ge
 
 ## Example usage
 
+### Basic example
+
 ```yml
 name: CI
 on: [push, pull_request]
@@ -45,13 +47,7 @@ jobs:
           github-token: ${{secrets.GITHUB_TOKEN}}
 ```
 
-**Note**
-
-- The GitHub token is automatically provided by Github Actions, which we access using `secrets.GITHUB_TOKEN` and supply to the action as an input `github-token`.
-- This action must be used in the context of a Pull Request. If the workflow can be triggered by other events (e.g. push), make sure to include `github.event_name == 'pull_request'` in the action conditions, as shown in the example.
-- Make sure to use `needs: <jobs>` to delay the auto-merging until CI checks (test/build) are passed.
-
-## With `exclude`
+### With `exclude`
 
 ```yml
 steps:
@@ -61,3 +57,18 @@ steps:
       github-token: ${{secrets.github_token}}
       exclude: ['react']
 ```
+
+## Limitations
+
+One known limitation of using a GitHub action to automatically merge Pull Requests is that the result of the merge will not trigger any workflow run.
+
+What this means in practice is that after this action merges a Pull Request, no workflows are run on the commit merged to the target branch.
+
+This is a known limitation described in the [documentation](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#triggering-new-workflows-using-a-personal-access-token) which prevents triggering of recursive workflow runs.
+
+## Notes
+
+- The GitHub token is automatically provided by Github Actions, which we access using `secrets.GITHUB_TOKEN` and supply to the action as an input `github-token`.
+- This action must be used in the context of a Pull Request. If the workflow can be triggered by other events (e.g. push), make sure to include `github.event_name == 'pull_request'` in the action conditions, as shown in the example.
+- Make sure to use `needs: <jobs>` to delay the auto-merging until CI checks (test/build) are passed.
+- If you want to use GitHub's [auto-merge](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request) feature but still use this action to approve Pull Requests without merging, use `approve-only: true`.