README.yaml

---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: github-commenter

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/github-commenter

# Badges to display
badges:
  - name: "Build Status"
    image: "https://github.com/cloudposse/github-commenter/workflows/go/badge.svg?branch=master"
    url: "https://github.com/cloudposse/github-commenter/actions"
  - name: "Docker Status"
    image: "https://github.com/cloudposse/github-commenter/workflows/docker/badge.svg?branch=master"
    url: "https://github.com/cloudposse/github-commenter/actions"
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/github-commenter.svg"
    url: "https://github.com/cloudposse/github-commenter/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

# Short description of this project
description: |-
  Command line utility for creating GitHub comments on Commits, Pull Request Reviews, Pull Request Files, Issues and Pull Requests.

  GitHub API supports these types of comments:

  * [Comments on Repos/Commits](https://developer.github.com/v3/repos/comments)
  * [Comments on Pull Request Reviews](https://developer.github.com/v3/pulls/reviews/#create-a-pull-request-review)
  * [Comments on Pull Request Files](https://developer.github.com/v3/pulls/comments)
  * [Comments on Issues](https://developer.github.com/v3/issues/comments)
  * [Comments on Pull Requests (in the global section)](https://developer.github.com/v3/issues/comments)

  Since GitHub considers Pull Requests as Issues, `Comments on Issues` and `Comments on Pull Requests` use the same API.

  The utility supports all these types of comments (`commit`, `pr-review`, `pr-file`, `issue`, `pr`).

related:
  - name: "github-status-updater"
    description: "Command line utility for updating GitHub commit statuses and enabling required status checks for pull requests"
    url: "https://github.com/cloudposse/github-status-updater"
  - name: "slack-notifier"
    description: "Command line utility to send messages with attachments to Slack channels via Incoming Webhooks"
    url: "https://github.com/cloudposse/slack-notifier"

screenshots:
  - name: "PR"
    description: "GitHub PR Review Comment"
    url: "images/github-pr-review-comment.png"

# How to use this project
usage: |-
  __NOTE__: Create a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) with `repo:status` and `public_repo` scopes.

  __NOTE__: The utility accepts parameters as command-line arguments or as ENV variables (or any combination of command-line arguments and ENV vars).
  Command-line arguments take precedence over ENV vars.


  | Command-line argument |  ENV var                     |  Description                                                                                                                                                                      |
  |:----------------------|:-----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
  | token                 | GITHUB_TOKEN                 | Github access [token](https://help.github.com/articles/creating-an-access-token-for-command-line-use)                                                                             |
  | owner                 | GITHUB_OWNER                 | Github repository owner (_e.g._ `cloudposse`)                                                                                                                                     |
  | repo                  | GITHUB_REPO                  | Github repository name (_e.g._ `github-commenter`)                                                                                                                                |
  | type                  | GITHUB_COMMENT_TYPE          | Comment type: `commit`, `pr`, `issue`, `pr-review` or `pr-file`                                                                                                                   |
  | sha                   | GITHUB_COMMIT_SHA            | Commit SHA. Required when `type=commit` or `type=pr-file`                                                                                                                         |
  | number                | GITHUB_PR_ISSUE_NUMBER       | Pull Request or Issue number. Required for all comment types except for `commit`                                                                                                  |
  | file                  | GITHUB_PR_FILE               | Pull Request File Name to comment on. For more info see [create comment](https://developer.github.com/v3/pulls/comments/#create-a-comment)                                        |
  | position              | GITHUB_PR_FILE_POSITION      | Position in Pull Request File. For more info see [create comment](https://developer.github.com/v3/pulls/comments/#create-a-comment)                                               |
  | template              | GITHUB_COMMENT_TEMPLATE      | Template to format comment (optional). Supports `Go` [templates](https://golang.org/pkg/text/template). _E.g._ `My comment:<br/>{{.}}`. Use either `template` or `template_file`  |
  | template_file         | GITHUB_COMMENT_TEMPLATE_FILE | The path to a template file to format comment (optional). Supports `Go` templates. Use either `template` or `template_file`                                                       |
  | format                | GITHUB_COMMENT_FORMAT        | Alias of `template`                                                                                                                                                               |
  | format_file           | GITHUB_COMMENT_FORMAT_FILE   | Alias of `template_file`                                                                                                                                                          |
  | comment               | GITHUB_COMMENT               | Comment text. If neither `comment` nor `GITHUB_COMMENT` provided, will read from `stdin`                                                                                          |
  | delete-comment-regex  | GITHUB_DELETE_COMMENT_REGEX  | Regex to find previous comments to delete before creating the new comment. Supported for comment types `commit`, `pr-file`, `issue` and `pr`                                      |
  | edit-comment-regex    | GITHUB_EDIT_COMMENT_REGEX    | Regex to find previous comments to replace with new content, or create new comment if none found. Supported for comment types `commit`, `pr-file`, `issue` and `pr`               |
  | baseURL               | GITHUB_BASE_URL              | Github Enterprise URL. _E.g._ `https://github.example.com/api/v3`                                                                                                                 |
  | uploadURL             | GITHUB_UPLOAD_URL            | Github Enterprise Upload URL to pass to the Github client                                                                                                                         |
  | insecure              | GITHUB_INSECURE              | Boolean to ignore SSL certificate check                                                                                                                                           | 


  __NOTE__: The utility accepts the text of the comment from the command-line argument `comment`, from the ENV variable `GITHUB_COMMENT`, or from the standard input.
  Command-line argument takes precedence over ENV var, and ENV var takes precedence over standard input.
  Accepting comments from `stdin` allows using Unix pipes to send the output from another program as the input to the tool:

  ```sh
      cat comment.txt | github-commenter ...
  ```

  ```sh
      terraform plan 2>&1 | github-commenter -format "Output from `terraform plan`<br/>```{{.}}```"
  ```

  __NOTE__: The utility supports [sprig functions](http://masterminds.github.io/sprig/) in `Go` templates, allowing to use string replacement and Regular Expressions in the `format` argument.

  See [string functions](http://masterminds.github.io/sprig/strings.html) for more details.

  For example:

  ```sh
  GITHUB_COMMENT_FORMAT="Helm diff:<br><br><pre>{{regexReplaceAllLiteral `\\n` . `<br>` }}<pre>"
  ```

examples: |-
  The utility can be called directly or as a Docker container.

  ### Build the Go program locally

  ```sh
  go get

  CGO_ENABLED=0 go build -v -o "./dist/bin/github-commenter" *.go
  ```


  ### Run locally with ENV vars
  [run_locally_with_env_vars.sh](examples/run_locally_with_env_vars.sh)

  ```sh
  export GITHUB_TOKEN=XXXXXXXXXXXXXXXX
  export GITHUB_OWNER=cloudposse
  export GITHUB_REPO=github-commenter
  export GITHUB_COMMENT_TYPE=pr
  export GITHUB_PR_ISSUE_NUMBER=1
  export GITHUB_COMMENT_FORMAT="My comment:<br/>{{.}}"
  export GITHUB_COMMENT="+1 LGTM"

  ./dist/bin/github-commenter
  ```


  ### Run locally with command-line arguments
  [run_locally_with_command_line_args.sh](examples/run_locally_with_command_line_args.sh)

  ```sh
  ./dist/bin/github-commenter \
          -token XXXXXXXXXXXXXXXX \
          -owner cloudposse \
          -repo github-commenter \
          -type pr \
          -number 1 \
          -format "My comment:<br/>{{.}}" \
          -comment "+1 LGTM"
  ```

  ### Build the Docker image
  __NOTE__: it will download all `Go` dependencies and then build the program inside the container (see [`Dockerfile`](Dockerfile))


  ```sh
  docker build --tag github-commenter  --no-cache=true .
  ```


  ### Run in a Docker container with ENV vars
  [run_docker_with_env_vars.sh](examples/run_docker_with_env_vars.sh)

  ```sh
  docker run -i --rm \
          -e GITHUB_TOKEN=XXXXXXXXXXXXXXXX \
          -e GITHUB_OWNER=cloudposse \
          -e GITHUB_REPO=github-commenter \
          -e GITHUB_COMMENT_TYPE=pr \
          -e GITHUB_PR_ISSUE_NUMBER=1 \
          -e GITHUB_COMMENT_FORMAT="My comment:<br/>{{.}}" \
          -e GITHUB_COMMENT="+1 LGTM" \
          github-commenter
  ```


  ### Run with Docker
  Run `github-commenter` in a Docker container with local ENV vars propagated into the container's environment.
  [run_docker_with_local_env_vars.sh](examples/run_docker_with_local_env_vars.sh)

  ```sh
  export GITHUB_TOKEN=XXXXXXXXXXXXXXXX
  export GITHUB_OWNER=cloudposse
  export GITHUB_REPO=github-commenter
  export GITHUB_COMMENT_TYPE=pr
  export GITHUB_PR_ISSUE_NUMBER=1
  export GITHUB_COMMENT_FORMAT="Helm diff:<br><br><pre>{{regexReplaceAllLiteral `\\n` . `<br>` }}<pre>"
  export GITHUB_COMMENT="Helm diff comment"

  docker run -i --rm \
          -e GITHUB_TOKEN \
          -e GITHUB_OWNER \
          -e GITHUB_REPO \
          -e GITHUB_COMMENT_TYPE \
          -e GITHUB_PR_ISSUE_NUMBER \
          -e GITHUB_COMMENT_FORMAT \
          -e GITHUB_COMMENT \
          github-commenter
  ```


  ### Run with Docker using Env File
  Run the `github-commenter` in a Docker container with ENV vars declared in a file.
    [run_docker_with_env_vars_file.sh](examples/run_docker_with_env_vars_file.sh)

  ```sh
  docker run -i --rm --env-file ./example.env github-commenter
  ```


  ### `delete-comment-regex` example 1
  Delete all previous comments on Pull Request #2 that contain the string `test1` in the body of the comments and create a new PR comment

  ```sh
  ./dist/bin/github-commenter \
          -token XXXXXXXXXXXXXXXX \
          -owner cloudposse \
          -repo github-commenter \
          -type pr \
          -number 2 \
          -format "{{.}}" \
          -delete-comment-regex "test1" \
          -comment "New Pull Request comment"
  ```

  ### `delete-comment-regex` example 2
  Delete all previous comments on Issue #1 that contain the string `test2` at the end of the comment's body and create a new Issue comment

  ```sh
  ./dist/bin/github-commenter \
          -token XXXXXXXXXXXXXXXX \
          -owner cloudposse \
          -repo github-commenter \
          -type issue \
          -number 1 \
          -format "{{.}}" \
          -delete-comment-regex "test2$" \
          -comment "New Issue comment"
  ```

  ### `delete-comment-regex` example 3
  Delete all previous commit comments that contain the string `test3` in the body and create a new commit comment

  ```sh
  ./dist/bin/github-commenter \
          -token XXXXXXXXXXXXXXXX \
          -owner cloudposse \
          -repo github-commenter \
          -type commit \
          -sha xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
          -format "{{.}}" \
          -delete-comment-regex "test3" \
          -comment "New commit comment"
  ```


  ### `delete-comment-regex` example 4
  Delete all previous comments on a Pull Request file `doc.txt` that contain the string `test4` in the body of the comments and create a new comment on the file

  ```sh
  ./dist/bin/github-commenter \
          -token XXXXXXXXXXXXXXXX \
          -owner cloudposse \
          -repo github-commenter \
          -type pr-file \
          -sha xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
          -number 2 \
          -file doc.txt \
          -position 1 \
          -format "{{.}}" \
          -delete-comment-regex "test4" \
          -comment "New comment on the PR file"
  ```

  ### `edit-comment-regex`
  
  The `-edit-comment-regex` flag operates similarly to the `-delete-comment-regex` except existing comments will be updated instead of deleted. If no matching comment is found a new comment is created.

# Contributors to this project
contributors:
  - name: "Erik Osterman"
    homepage: "https://github.com/osterman"
    avatar: "http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144"
    github: "osterman"
  - name: "Andriy Knysh"
    homepage: "https://github.com/aknysh/"
    avatar: "https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144"
    github: "aknysh"
  - name: "Igor Rodionov"
    homepage: "https://github.com/goruha/"
    avatar: "http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144"
    github: "goruha"