can-merge

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.

Installation

The can-merge tool requires the latest Node.js version 14 or above. We recommend using npx to run can-merge.

npx can-merge

However, to install it globally, run the following lines in your terminal:

npm install -g can-merge

NOTE: If you are using Linux, you may need prepend sudo before the npm install command.

Usage

$ 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_TOKEN or $GITHUB_TOKEN, or pass it with the -t option.

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.

CLI Reference

--help

Shows the usage information as in Usage section.

-c, --commit

Used to check the commit status.

-p, --pr

Used to specify the Pull Request number being used on GitHub.

--remote

Used to specify the remote to check.

-r, --repo

Used to specify the repository if there is no GitHub remote configured or if it is different from the repository you are currently in.

--sha

Specify the commit-ish to be used. Defaults to the current SHA.

--retryDelay

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.

-t, --token

Used to specify the GitHub Personal Access Token needed to authenticate queries to the GitHub API.

-w, --watch

Used to specify if the tool should keep polling for changes in the status checks untill all of them have completed.

License

MIT License