GitHub action for creating, updating, and hiding comments on pull requests

1. A message body is ready to be used as a comment. This can be either passed directly via comment-body or as a file via comment-body-path.

All inputs for this action are summarized below for quick reference:

- name: Create PR Comment
  uses: colpal/actions-pr-comment@v1
  if: ${{ !cancelled() }}
  with:
    comment-id: "my-check"
    comment-body: "My comment here"
    conclusion: "${{ steps.<step_id>.outcome }}"
    github-token: "${{ github.token }}"
    render-markdown: true
    sync-conclusion: false
    update-mode: "create"
    verbose-logging: false

To ensure this action runs after a workflow step, even if that step fails, use if: ${{ !cancelled() }}. This lets the comment action run unless the workflow is cancelled.

Avoid using continue-on-error: true on the previous step. While it allows the comment action to run after a failure, it also marks the workflow as successful, which can be misleading.

Use if: ${{ !cancelled() }} on this action to run it after any step, regardless of success or failure, while keeping the workflow status accurate.

For this action to do its job to the fullest, it will require some permissions. In the workflow file that is calling this action, there should be a permission block. The following permissions are required for secrets.GITHUB_TOKEN in the workflow:

permissions:
  pull-requests: write

• pull-requests: write → this is to create and update comments on a pull request
  • write permissions come with read permissions, which are required to find all comments on a pull request in order to find previous comments to update.

The action places or updates a comment in the pull request. The comment includes:

• The supplied comment-body or contents of comment-body-path.
• Hidden identifiers at the beginning of the body:
  • <!-- comment-id: my-check --> (for identifying the comment)
  • <!-- conclusion: success --> (for tracking status and visibility)

The comment-id input is a unique identifier for the comment. It is an hidden identifier that is placed at the beginning of the comment body. It is used to identify the comment in the pull request and to track its visibility. When updating or hiding future comments, the action will look for a comment with the same comment-id and update it accordingly.

Furthermore, it allows the same user (typically github-actions[bot]) to leave multiple comments at the same time without conflicting with each other. It serves as another identifier to distinguish between different comments. With this, this action can be apart of multiple workflows that leave comments on the same pull request, and not conflict with each other's update methods and contents.

The conclusion input is a hidden identifier that tracks the status of the current run. It works with sync-conclusion to control comment visibility. Use steps.<step_id>.outcome for this value. Possible values and their effects:

This flag controls whether the comment body should be rendered as markdown or not. Useful for files like Terraform plans which might not want to be rendered as markdown.

• If render-markdown is true, the comment body will be rendered as markdown.
  • **bold** will be rendered as bold instead of **bold**.
• If render-markdown is false, the comment body will be rendered as plain text, such that markdown formatting is not applied.
  • **bold** will be rendered as **bold** instead of bold.

This flag controls whether successful comments are hidden automatically. When set to "true":

• If conclusion is success, the comment is hidden.
  • If conclusion is success and it's the first comment, then the comment is not created at all.
• If updating a previous comment with failure or neutral, it will be hidden after update.
• If a future comment is no longer success, it will update and unhide itself according to update-mode.
• Hidden comments remain up-to-date, so if you unhide them, the content is correct.

The update-mode input controls how the action handles existing comments with the same comment-id.

Creating New Comment and Hiding Previous Comment

Replacing Previous Comment

Appending to Previous Comment

Performing No Updates to Previous Comment

Set verbose-logging: true to enable detailed logs for debugging.

Posts a comment to the pull request with the message "Linting passed successfully!".

- name: Create PR Comment
  uses: colpal/actions-pr-comment@v1
  if: ${{ !cancelled() }}
  with:
    comment-id: "lint-check"
    comment-body: "Linting passed successfully!"
    conclusion: "${{ steps.<step_id>.outcome }}"
    github-token: "${{ secrets.github-token }}"
    update-mode: "create"
    sync-conclusion: true

Posts the contents of path/test-results.md as the comment body, replacing any previous comment for the same check.

- name: Create PR Comment
  uses: colpal/actions-pr-comment@v1
  if: ${{ !cancelled() }}
  with:
    comment-id: "test-results"
    comment-body-path: "path/test-results.md"
    conclusion: "${{ steps.<step_id>.outcome }}"
    github-token: "${{ secrets.github-token }}"
    verbose-logging: true
    update-mode: "replace"
    sync-conclusion: false

Within the .github/workflows directory, there are test workflows that demonstrate most configurations of this action. They are grouped by functionality and can be added to an open pull request by attaching a matching label to it. The workflow will run and post comments to the pull request on label attachment, pushes to the branch, and when the pull request is opened (such that closing and reopening will maintain the label and trigger a pull-request open event).

• Test Comment Conclusions
  • Tests conclusion functionality
  • Label: test-conclusions
• Test Comment Inputs
  • Tests comment-body, comment-body-path, and render-markdown functionality
  • Label: test-inputs
• Test Comment Sync Conclusions
  • Tests sync-conclusion functionality
  • Label: test-sync-conclusions
• Test Update Mode
  • Tests update-mode functionality
  • Label: test-update-mode

Below are some already implemented instances of colpal workflows and actions utilizing this action:

• Airflow Dagbag Scanner
• Airflow Validation

This project includes a test directory containing a test suite that covers the functionality of this action. The tests are written in Jest and can be run using npm test. The test suite is run automatically by the test-and-coverage.yaml workflow, which ensures that at least 95% of the lines, branches, functions, and statements are covered and that there are no failing tests. You can read more about the test suite here.

See CHANGELOG.md for a list of changes.