can-merge is a command-line utility that enables you to check whether a certain pull request can actually be merged without navigating to the web UI. It uses the GitHub GraphQL API to fetch the latest state of the status checks that might be running and evaluates if the PR can be merged.
The can-merge tool requires the latest Node.js version 14 or above. We recommend using npx to run can-merge.
npx can-mergeHowever, to install it globally, run the following lines in your terminal:
npm install -g can-mergeNOTE: If you are using Linux, you may need prepend sudo before the npm install command.
$ npx can-merge --help
Usage: can-merge -p <pr> [-r <repo>]
Options:
--version Show version number [boolean]
--help Show help [boolean]
-c, --commit check commit status [boolean] [default: false]
-p, --pr pull request [string]
--remote remote name [string] [default: "origin"]
-r, --repo repository [string] [default: "ljharb/can-merge"]
--retryDelay delay before polling the api [number] [default: 5000]
-s, --sha commit SHA, or any git commit-ish [string] [default: "HEAD"]
--token github access token [string] [required]
-w, --watch watch pending checks [boolean]
NOTE:
- Export your GitHub Personal Access Token and set it as
$GH_TOKENor$GITHUB_TOKEN, or pass it with the-toption.
The can-merge tool will exit with a non-zero exit code if the pull request is not mergeable or blocked. It will exit with the exit code 0 if the pull request can be merged. You can use this tool with other scripts and tool to perform actions based on the exit code of this tool.
For example, you can use the can-merge tool to check if a pull request can be merged before merging it using a custom shell script.
Shows the usage information as in Usage section.
Used to check the commit status.
Used to specify the Pull Request number being used on GitHub.
Used to specify the remote to check.
Used to specify the repository if there is no GitHub remote configured or if it is different from the repository you are currently in.
Specify the commit-ish to be used. Defaults to the current SHA.
Used to specify the delay before polling the GitHub API for checking if the state of status checks have changed. To be used along with the -w, --watch option.
Used to specify the GitHub Personal Access Token needed to authenticate queries to the GitHub API.
Used to specify if the tool should keep polling for changes in the status checks untill all of them have completed.