From d8f33f73834cfbd4aca1367594d2e1e7a52e4a1c Mon Sep 17 00:00:00 2001 From: Simone Busoli Date: Thu, 4 Mar 2021 14:10:19 +0100 Subject: [PATCH] docs: document how to use approve-only with GitHub's automerge (#10) --- README.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 34d78cd2..6427f2a8 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This action automatically approves and merges dependabot PRs. ### `github-token` -**Required** A GitHub token. +**Required** A GitHub token. See below for additional information. ### `exclude` @@ -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: ` to delay the auto-merging until CI checks (test/build) are passed. - -## With `exclude` +### With `exclude` ```yml steps: @@ -61,3 +57,24 @@ steps: github-token: ${{secrets.github_token}} exclude: ['react'] ``` + +## Notes + +- A GitHub token is automatically provided by Github Actions, which can be accessed using `secrets.GITHUB_TOKEN` and supplied to the action as an input `github-token`. +- Only the [GitHub native Dependabot integration](https://docs.github.com/en/github/administering-a-repository/keeping-your-dependencies-updated-automatically) is supported, the old [Dependabot Preview app](https://github.com/marketplace/dependabot-preview) isn't. +- 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: ` 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`. + +## Limitations + +One known limitation of using a GitHub action with the built-in GitHub Token to automatically merge Pull Requests is that the result of the merge will not trigger a workflow run. + +What this means in practice is that after this action merges a Pull Request, no workflows are run on the commit made to the target branch. + +This is a known behavior 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. + +Alternative options are: + +- use a personal access token, as described in the documentation +- use this action only for approving and using GitHub's auto-merge to merge Pull Requests