GitHub Action Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub Action Integration for code-review-graph provides an automated, local-first mechanism for generating risk-scored and graph-aware review comments directly on pull requests. It leverages the core project's ability to build a Tree-sitter knowledge graph on the GitHub runner, analyzing the impact of changes without transmitting source code to external services.
The integration automates the lifecycle of the code review graph within a CI/CD pipeline, including environment setup, graph building/updating, change detection, and reporting. It specifically targets Pull Request events to provide "sticky" comments that update as new commits are pushed, ensuring developers have immediate feedback on the architectural impact and risks of their changes.
Sources: action.yml:1-12, README.zh-CN.md:16-19
Workflow Architecture and Data Flow
The GitHub Action follows a composite execution strategy that bridges the CLI tools with the GitHub API. The process begins by resolving the appropriate Git base reference to compare against, followed by an incremental or full build of the knowledge graph stored in a SQLite database.
Integration Pipeline
The following diagram illustrates the sequential steps taken by the action during a CI run:
The action utilizes a specific caching strategy for the .code-review-graph directory, keyed by the current schema version and lockfile hashes, to ensure that incremental updates are as fast as possible on the runner.
Sources: action.yml:45-84, README.zh-CN.md:120-125
Input Configuration
The action provides several inputs to customize the behavior of the review process and the strictness of the CI gate.
| Input | Description | Default |
|---|---|---|
github-token | Token used to post PR comments. Requires pull-requests: write. | N/A (Required) |
comment | Whether to post and maintain a sticky PR comment with the report. | true |
fail-on-risk | Risk level to fail the job: none, high (>= 0.70), or critical (>= 0.85). | none |
python-version | Version of Python used to execute the tools. | 3.12 |
Sources: action.yml:17-36
Core Components and Execution Logic
1. Base Reference Resolution
The action identifies the target branch for comparison using the github.base_ref. If the event is not a pull request, it defaults to HEAD~1. This reference is then stored in the CRG_BASE environment variable to ensure consistency across subsequent tool calls.
Sources: action.yml:58-69
2. Change Detection and Risk Scoring
The integration invokes the detect-changes command via the CLI. This command maps the git diff to affected functions, execution flows, and communities within the graph. It generates a JSON report that includes risk scores based on architectural hotspots and test coverage gaps.
Sources: action.yml:81-84, code_review_graph/cli.py:535-560
3. Markdown Rendering and PR Interaction
The integration uses a dedicated script, render_pr_comment.py, to transform the JSON analysis into a human-readable Markdown report. The action then uses the GitHub CLI (gh api) to search for an existing comment containing the <!-- code-review-graph-report --> marker.
- New Comments: If no marker is found, a
POSTrequest creates a new comment. - Existing Comments: If a marker is found, a
PATCHrequest updates the existing comment to keep the PR conversation clean.
Sources: action.yml:86-110, tests/test_action_render.py
4. Risk Gating
If the fail-on-risk input is configured, the action re-runs the rendering script with a --fail-on-risk flag. This checks the aggregate risk score from the JSON report against the configured threshold (e.g., 0.70 for High) and exits with a non-zero code if the threshold is met, effectively failing the CI build.
Sources: action.yml:112-120
Implementation Details
The integration relies on the code-review-graph CLI being installed in the runner's environment. The CLI provides the underlying logic for the tools used in the action.
# Example of the CLI command structure used by the action
# Sources: code_review_graph/cli.py:535-560
def _handle_detect_changes(args, store, repo_root):
from .changes import analyze_changes
changed = get_changed_files(repo_root, args.base)
result = analyze_changes(
store,
changed,
repo_root=str(repo_root),
base=args.base,
)
# Action consumes this JSON output
print(json.dumps(result, indent=2, default=str))
The action also integrates with the run_postprocess logic to ensure execution flows and community structures are up-to-date before analysis is performed.
Sources: code_review_graph/main.py:126-146, code_review_graph/tools/docs.py:180-210
Summary
The GitHub Action Integration automates the deployment of the code-review-graph as a CI gate. By combining local graph building on the runner with sticky PR comments and risk-based exit codes, it provides a feedback loop for developers to understand the structural impact of their code changes in real-time.