GitHub PR Commenter (ghpc)

GitHub PR Commenter (ghpc) is a tool that automates the process of executing commands and posting their output as comments on GitHub Pull Requests (PRs). Inspired by Atlantis, ghpc aims to streamline the integration of command execution and result reporting within the PR workflow.

Motivation

The motivation behind creating ghpc is to provide a seamless way to run various checks and commands automatically and post their results directly to GitHub pull requests. By automating this process, ghpc helps developers get immediate feedback on their changes, leading to faster and more efficient code reviews. The tool aims to:

Improve Developer Productivity: Automate repetitive tasks and provide instant feedback on pull requests.
Enhance Collaboration: Enable better collaboration by ensuring all team members have access to the latest results of automated checks.
Increase Code Quality: Automate linting, testing, and other checks to ensure that only high-quality code gets merged.

Overview

ghpc leverages GitHub's API and GraphQL to interact with PRs and comments. It allows you to run commands, capture their output, and post the output as comments on GitHub PRs. The tool is designed to be extensible and configurable, with a focus on error handling, logging, and testing.

Features

Comment Automation: Automatically posts comments on pull requests with command outputs.
GitHub Actions Integration: Uses GitHub Actions for building, testing, and releasing.
Multi-Architecture Builds: Supports builds for multiple architectures including Linux and Darwin (AMD64 and ARM64).
Output Handling: Handles command outputs exceeding 55000 characters by splitting them into multiple comments.
Error Handling: Provides detailed error handling and logging using the zap logging package.
Modular Design: Follows a modular code structure for easy maintenance and extension.
Environment Variable Configuration: Configurable via environment variables for flexible setup.
Enhanced Logging: Uses structured logging with zap for better traceability and debugging.
Atlantis Integration: Designed to be used in Atlantis Docker images for custom workflows.

Integration with Atlantis

ghpc is created with the intent to be used within Atlantis Docker images for custom workflows. This allows for running commands (e.g., tflint), capturing their output, and posting the results as comments on PRs. It enables capturing output from multiple projects in one PR in Atlantis and comments on the PR output with commit status checks for each command.

Installation

Prerequisites

GitHub token set as GITHUB_TOKEN environment variable.

Option 1: Download and Install Using Script

To download and install the latest binary, run the following command:

curl -s https://raw.githubusercontent.com/EdwinPhilip/gh-pr-commenter/main/install/script.sh | bash

This script will:

Detect your operating system and architecture.
Fetch the latest release from GitHub.
Download the appropriate binary to a temporary directory.
Copy the binary to /usr/local/bin.
Clean up the temporary directory.

Option 2: Download from GitHub Releases Manually

Visit the GitHub releases page.
Download the appropriate binary for your operating system and architecture (e.g., ghpc-linux-amd64, ghpc-darwin-arm64).

Verify the Download

chmod +x ghpc-<os>-<arch>
sudo cp ghpc-<os>-<arch> /usr/local/bin/ghpc
ghpc --version

Example:

For Linux AMD64:

chmod +x ghpc-linux-amd64
sudo cp ghpc-linux-amd64 /usr/local/bin/ghpc
ghpc --version

Configuration

Set environment variables:
- HEAD_COMMIT: The commit SHA to set the status on.
- PROJECT_NAME: The name of the project.
- GH_STATUS_CONTEXT: The status context.
- WORKSPACE: The workspace name.
- BASE_REPO_OWNER: Owner of the base repository.
- BASE_REPO_NAME: Name of the base repository.
- PULL_NUM: PR number where the comments will be posted.
- GITHUB_TOKEN: GitHub token.
Customize the template.md file for comment formatting.

Usage

Step 1: Execute a Command and Capture its Output

The ghpc exec command executes a specified command and captures its output in a file.

ghpc exec "tflint"

This will execute the tflint command and save the output to a file in the temporary directory specified by the environment variable TMP_GHPC_DIR (default is /tmp/ghpc).

Step 2: Post the Captured Output as a PR Comment

The ghpc comment command reads the captured output file and posts its content as a comment on the specified pull request.

ghpc comment "tflint"

This will read the output file generated by the ghpc exec command and post its content as a comment on the pull request specified by the environment variables.

Development

For detailed development instructions, see docs/development.md.

Testing

For detailed testing instructions, see docs/testing.md.

TODO

For a list of TODO items and future enhancements, see docs/TODO.md.

Example Workflow

Setup GitHub Actions: Integrate ghpc into your GitHub Actions workflow to automatically run commands and post results on PRs.
Configure Environment Variables: Set the necessary environment variables in your GitHub Actions workflow.
Run Commands: Use ghpc to run commands such as linting, testing, or security checks.
Post Results: Automatically post the results as comments on the relevant pull request.

Sample GitHub Actions Workflow

name: CI

on:
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Go
        uses: actions/setup-go@v2
        with:
          go-version: 1.21.6

      - name: Install ghpc
        run: |
          curl -s https://raw.githubusercontent.com/EdwinPhilip/gh-pr-commenter/main/install/script.sh | bash

      - name: Run TFLint and post results
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          HEAD_COMMIT: ${{ github.event.pull_request.head.sha }}
          BASE_REPO_OWNER: ${{ github.repository_owner }}
          BASE_REPO_NAME: ${{ github.event.repository.name }}
          PULL_NUM: ${{ github.event.pull_request.number }}
        run: |
          ghpc exec "tflint"
          ghpc comment "tflint"

License

This project is licensed under the MIT License - see the LICENSE file for details.