> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# narrativescience/ghpr

Set of git utilities to manage GitHub Pull Requests in CI. This orb was created to address the need to simulate the result of merging the head branch into a PR's target base branch


## Commands

### build-prospective-branch

Builds the prospective merge branch by merging the head branch into the pull request's base branch.
Requires `GITHUB_EMAIL`, `GITHUB_USERNAME`, and `GITHUB_TOKEN` to be set as environment variables.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `force` | boolean | false | If `true`, this command will exit successfully even if the merge fails.
By default, this is disabled, to allow failing when a merge conflict occurs.
 |
| `get_commit_message` | boolean | false | If true, also sets GITHUB_PR_COMMIT_MESSAGE. This requires an additional API call. |

### get-pr-info

Gets and sets the following environment variables:
    * `GITHUB_PR_BASE_BRANCH` - The base branch for the PR.
    * `GITHUB_PR_NUMBER` - The number of the PR.
    * `GITHUB_PR_TITLE` - The title of the PR.
    * `GITHUB_PR_COMMIT_MESSAGE` - The current commit's message. (Optional)
    * `GITHUB_PR_AUTHOR_USERNAME` - The PR author's username.
    * `GITHUB_PR_AUTHOR_NAME` - The PR author's name. (Optional)
    * `GITHUB_PR_AUTHOR_EMAIL` - The PR author's email address. (Optional)
Requires  `GITHUB_TOKEN` to be set as an environment variable.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `get_commit_message` | boolean | false | If true, also sets GITHUB_PR_COMMIT_MESSAGE. This requires an additional API call.
 |
| `get_pr_author_email` | boolean | false | If true, also sets GITHUB_PR_AUTHOR_EMAIL. This requires an additional API call.
 |
| `get_pr_author_name` | boolean | false | If true, also sets GITHUB_PR_AUTHOR_NAME. This requires an additional API call.
 |

### post-pr-comment

Post a comment on the pull request.
Requires `GITHUB_TOKEN` to be set as an environment variable.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `comment` | string |  | Content of the comment to post |
| `when` | enum | on_success | Condition for when the comment should be created |

### slack-pr-author

Send a Slack direct message to the PR author, or to a channel, @mentioning the PR author.
Requires `SLACK_OAUTH_TOKEN` to be set as an environment variable. If you'd like to have the workflow name be displayed as well, `CIRCLECI_API_TOKEN` should be set. For more details, see https://github.com/NarrativeScience/circleci-orb-ghpr#enabling-slack-notifications.

The following are the mechanisms (see `get_slack_user_by`) by which a Slack user can be found for the PR author:
    * `email` - Find a Slack user with the same email address as GITHUB_PR_AUTHOR_EMAIL.
    * `display_name` - Find a Slack user with their Slack profile name, i.e. "Display name", exactly equal to GITHUB_PR_AUTHOR_USERNAME. First match only.
    * `real_name` - Find a Slack user with their Slack profile real_name field, i.e. "Full name", exactly equal to GITHUB_PR_AUTHOR_NAME. Fist match only.
    * `title_tag` - Find a Slack user with a Slack profile title field, i.e. "What I do", containing the string "[gh:GITHUB_PR_AUTHOR_USERNAME]". First match only.
    * `meseeks` - Try to employ all the mechanisms above, in order, to find a Slack user.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | Optional channel to send a message to, ex. `#some-channel`.
If provided, will message the channel but @mention the PR author.
Otherwise, the message is sent to the PR author directly.
 |
| `color` | string | #DDDDDD | The color to format the message with.
Should be a hex value wrapped in quotes because we're in YAML land.
 |
| `get_slack_user_by` | enum | email | The mechanism by which to find the PR author's associated Slack user ID. |
| `message` | string |  | The message to send.
Supports Slack mrkdown syntax - https://api.slack.com/reference/surfaces/formatting#basics
 |
| `pass_on_fail` | boolean | true | Whether or not the command should exit if anything fails. Ultimately, sending a Slack message is a nice-to-have, but setting this to `fail` is a way to enforce enabling Slack messages. An example scenario where it would be useful is if messages are sent to a channel and the PR author should be tagged to get their attention.
 |
| `when` | enum | on_success | Condition for when the message should be sent. |

## Examples

### test-pull-request

Run pull request tests on a temporary branch resulting from merging the PR's head branch into the base branch. Post a PR comment on test failure, but Slack the author on success.


```yaml
jobs:
  run-test:
    machine: true
    steps:
      - ghpr/build-prospective-branch
      - some-test-command
      - ghpr/post-pr-comment:
          comment: some message
          when: on_fail
      - ghpr/slack-pr-author:
          color: '#1CBF43'
          get_slack_user_by: meseeks
          message: ':tada: Tests passed!'
orbs:
  ghpr: narrativescience/ghpr@x.y.z
version: 2.1
```