PR

PR is a CLI tool that operates Pull Request on a rule-based basis.

Get Started

$ curl -L https://github.com/k-kinzal/pr/releases/download/v0.2.1/pr_linux_amd64.tar.gz | tar xz
$ cp pr /usr/local/bin/pr
$ pr --help
PR operates multiple Pull Request

Usage:
  pr [flags]
  pr [command]

Available Commands:
  assignee    Manipulate assignees that match a rule
  check       Check if PR matches the rule and change PR status
  help        Help about any command
  label       Manipulate labels that match a rule
  merge       Merge PR that matches a rule
  review      Add review to PRs that match rules
  show        Show PR that matches a rule
  validate    Validate the rules

Flags:
      --exit-code      returns an exit code of 127 if no PR matches the rule
  -h, --help           help for pr
      --no-exit-code   always returns 0 even if an error occurs
      --rate int       API call seconds rate limit (default 10)
      --token string   personal access token to manipulate PR [GITHUB_TOKEN]
      --version        version for pr

Use "pr [command] --help" for more information about a command.

Operations

Merge

Merge PRs that match the rule.

$ pr merge [owner]/[repo] --with-statuses -l 'state == `"open"`' -l 'length(statuses[?state == `"success"`]) > `3`'
[...]

Review

Add a review to PRs that match the rule.

$ pr review [owner]/[repo] --action "approve" --with-statuses -l 'state == `"open"`' -l 'length(statuses[?state == `"success"`]) > `3`'
[...]

--action "approve" adds approval to the PR that matches the rule.

Label

Append/Remove/Replace labels to PRs that match the rule.

$ pr label [owner]/[repo] -l 'state == `"open"`' --action "append" --label "foo"
...
$ pr label [owner]/[repo] -l 'state == `"open"`' --action "remove" --label "foo"
...
$ pr label [owner]/[repo] -l 'state == `"open"`' --action "replace" --label "foo"
...

--action "append" appends the specified label to the PR that matches the rule. --action "remove" removes the label specified for the PR that matched the rule. --action "replace" replaces all labels on PR that match the rule with the specified label.

Assignee

Append/Remove/Replace assignees to PRs that match the rule.

$ pr assignees [owner]/[repo] -l 'state == `"open"`' --action "append" --assignee "foo"
...
$ pr assignees [owner]/[repo] -l 'state == `"open"`' --action "remove" --assignee "foo"
...
$ pr assignees [owner]/[repo] -l 'state == `"open"`' --action "replace" --assignee "foo"
...

--action "append" appends the specified label to the PR that matches the rule. --action "remove" removes the label specified for the PR that matched the rule. --action "replace" replaces all labels on PR that match the rule with the specified label.

Check

When the PR CLI is run on the CI, the rule status is displayed separately from the CI. This is a solution to the problem where multiple CI statuses are displayed in GitHub Action.

$ pr check [owner]/[repo] -l 'number == `1`' -l 'state == `"open"`' -l 'length(statuses[?state == `"success"` && context == `"ci/circleci: test"`]) == `1`'
[...]

Check commands can perform conditional actions.

$ pr check [owner]/[repo] --merge -l 'number == `1`' -l 'state == `"open"`' -l 'length(statuses[?state == `"success"`]) == `1`'
[...]

For PR with number == 1, merge if the condition is met, or change status to pending if the condition is not met.

Show

Check the PR that matches the rule.

$ pr show [owner]/[repo] -l 'state == `"open"`'
[...]

If you want to make an error if there is no PR that matches the rule, specify `--exit-code``.

$ pr show [owner]/[repo] --exit-code -l 'number == `1`' -l 'state == `"open"`'
[...]

Validate

Validate the rules.

$ pr validate [owner]/[repo] --with-statuses -l 'state == `"open"`' -l 'length(statuses[?state == `"success"`]) > `0`' -l 'user.name == `"github-action[bot]"`'
[x] state == `"open"`: 1 PRs matched the rules
[x] length(statuses[?state == `"success"`]) > `0`: 1 PRs matched the rules
[ ] user.name == `"github-action[bot]"`: no PR matches the rule
[]

Rule Specification

JSON

JSON

See below for a detailed description of each item.

• Pull Requests
• Comments
• Reviews
• Commits
• Statuses
• Checks

"comments", "reviews", "commits", "statuses"", and "checks" cannot be used by default with PR link relation. If the parameter is required, specify option --with-comments, --with-reviews, --with-commits, --with-statuses, --with-checks or --with-all.

NOTE: --with-all options have very poor performance. Not recommended for uses other than debugging.

Rule Expression

In PR CLI, rules are specified using JMESPath.

$ pr show [owner]/[repo] -l 'state == `"open"`' -l 'length(statuses[?state == `"success"`]) >= 1'

[?state == `"open"`] | [?length(statuses[?state == `"success"`]) >= 1])]

The specified rule is converted to an expression that combines Filter Expression with a pipe.

Extend date string

The date string has been extended to be replaced with unix time.

$ pr show [owner]/[repo] -l 'now() == `"2006-01-02T15:04:05Z"`' -l 'now() > `"15:04:05"`'

[?`1571475658` >= `1136214245`] | [?`1571475658` >= `1571497445`]

If the date is in the format "2006-01-02T15:04:05Z ", it will be treated as unix time. The format of "15:04:05" is regarded as time and treated as unix time for the specified time of the day.

Extend Function

In pr, JMESPath can be extended to use original functions.

now()

$ pr show [owner]/[repo] -l 'now() == `"2006-01-02T15:04:05Z"`'

now() returns the current unix time.

GitHub Action

If you execute PR CLI with [GitHub Action], the rules are automatically completed by event type.

Number completion

• pull_request
• pull_request_review
• pull_request_review_comment

number == `[Pull Request Number]`

Head branch completion

• create
• deployment
• deployment_status
• push
• release

head.ref == `"[Branch Name]"`

SHA completion

• page_build
• status

head.sha == `\"[SHA]\"`

Please see the event trigger for details.

License