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.
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.
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.
- 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.
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.
- GitHub token set as
GITHUB_TOKEN
environment variable.
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.
- Visit the GitHub releases page.
- Download the appropriate binary for your operating system and architecture (e.g.,
ghpc-linux-amd64
,ghpc-darwin-arm64
).
chmod +x ghpc-<os>-<arch>
sudo cp ghpc-<os>-<arch> /usr/local/bin/ghpc
ghpc --version
For Linux AMD64:
chmod +x ghpc-linux-amd64
sudo cp ghpc-linux-amd64 /usr/local/bin/ghpc
ghpc --version
-
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.
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
).
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.
For detailed development instructions, see docs/development.md.
For detailed testing instructions, see docs/testing.md.
For a list of TODO items and future enhancements, see docs/TODO.md.
- 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.
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"
This project is licensed under the MIT License - see the LICENSE file for details.