# Comment Pull Request - GitHub Actions

## What is it ?

A GitHub/Forgejo action that comments with a given message the pull request linked to
the pushed branch. You can even put dynamic data thanks to
[Contexts and expression syntax](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions).

The action is also available as a JS library for integration into other actions.

This project is a fork of https://github.com/thollander/actions-comment-pull-request by
Térence Hollander.

## Usage

### Classic usage

```yml
on: pull_request

jobs:
  example_comment_pr:
    runs-on: ubuntu-latest
    name: An example job to comment a PR
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Comment PR
        uses: https://code.thetadev.de/actions/comment-pull-request@v1
        with:
          message: |
            Hello world ! :wave:
```

### Comment a file content

Thanks to the `filePath` input, a file content can be commented. You can either pass an
absolute filePath or a relative one that will be by default retrieved from
`GITHUB_WORKSPACE`. (Note that if both a `message` and `filePath` are provided,
`message` will take precedence.)

```yml
- name: PR comment with file
  uses: https://code.thetadev.de/actions/comment-pull-request@v1
  with:
    filePath: /path/to/file.txt
```

### Setting reactions

You can also set some reactions on your comments through the `reactions` input. It takes
only valid reactions and adds it to the comment you've just created. (See
https://docs.github.com/en/rest/reactions#reaction-types)

```yml
- name: PR comment with reactions
  uses: https://code.thetadev.de/actions/comment-pull-request@v1
  with:
    message: |
      Hello world ! :wave:
    reactions: eyes, rocket
```

### Specifying which pull request to comment on

You can explicitly input which pull request should be commented on by passing the
`pr_number` input. That is particularly useful for manual workflow for instance
(`workflow_run`).

```yml

---
- name: Comment PR
  uses: https://code.thetadev.de/actions/comment-pull-request@v1
  with:
    message: |
      Hello world ! :wave:
    pr_number: 123 # This will comment on pull request #123
```

### Update a comment

Editing an existing comment is also possible thanks to the `comment_tag` input.

Thanks to this parameter, it will be possible to identify your comment and then to
upsert on it. If the comment is not found at first, it will create a new comment.

_That is particularly interesting while committing multiple times in a PR and that you
just want to have the last execution report printed. It avoids flooding the PR._

```yml

---
- name: Comment PR with execution number
  uses: https://code.thetadev.de/actions/comment-pull-request@v1
  with:
    message: |
      _(execution **${{ github.run_id }}** / attempt **${{ github.run_attempt }}**)_
    comment_tag: execution
```

Note: the input `mode` can be used to either `upsert` (by default) or `recreate` the
comment (= delete and create)

## Inputs

### Action inputs

| Name                   | Description                                                                                                       | Required | Default                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| `GITHUB_TOKEN`         | Token that is used to create comments. Defaults to ${{ github.token }}                                            | ✅       |                                                          |
| `message`              | Comment body                                                                                                      |          |                                                          |
| `filePath`             | Path of the file that should be commented                                                                         |          |                                                          |
| `reactions`            | List of reactions for the comment (comma separated). See https://docs.github.com/en/rest/reactions#reaction-types |          |                                                          |
| `pr_number`            | The number of the pull request where to create the comment                                                        |          | current pull-request/issue number (deduced from context) |
| `comment_tag`          | A tag on your comment that will be used to identify a comment in case of replacement                              |          |                                                          |
| `recreate`             | Delete and recreate the comment instead of updating it                                                            |          | false                                                    |
| `create_if_not_exists` | Whether a comment should be created even if `comment_tag` is not found                                            |          | true                                                     |

## Outputs

### Action outputs

You can get some outputs from this actions :

| Name       | Description                            |
| ---------- | -------------------------------------- |
| `id`       | Comment id that was created or updated |
| `body`     | Comment body                           |
| `html_url` | URL of the comment created or updated  |

### Example output

```yaml
- name: Comment PR
  uses: https://code.thetadev.de/actions/comment-pull-request@v1
  id: hello
  with:
    message: |
      Hello world ! :wave:
- name: Check outputs
  run: |
    echo "id : ${{ steps.hello.outputs.id }}"
    echo "body : ${{ steps.hello.outputs.body }}"
    echo "html_url : ${{ steps.hello.outputs.html_url }}"
```

## Permissions

Depending on the permissions granted to your token, you may lack some rights. To run
successfully, this actions needs at least :

```yaml
permissions:   pull-requests: write
```

Add this in case you get `Resource not accessible by integration` error. See
[jobs.<job_id>.permissions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions)
for more information.

> Note that, if the PR comes from a fork, it will have only read permission despite the
> permissions given in the action for the `pull_request` event. In this case, you may
> use the `pull_request_target` event. With this event, permissions can be given without
> issue (the difference is that it will execute the action from the target branch and
> not from the origin PR).

## Contributing

### Build

The build steps transpiles the `src/main.ts` to `act/index.js` which is used in a NodeJS
environment. It is handled by `vercel/ncc` compiler.

```sh
$ npm run build
```