How the GitHub Action Integration for Risk-Scored PR Reviews Works

The code-review-graph GitHub Action is a composite action that runs entirely on the CI runner to build a local Tree-sitter knowledge graph, evaluates pull request changes using a multi-factor risk algorithm, and posts a sticky markdown comment containing a 0.0-1.0 risk score and token-savings estimate.

The tirth8205/code-review-graph repository delivers a local-first, security-focused integration that performs deterministic impact analysis without transmitting repository code to external services. By combining incremental graph construction, intelligent caching, and automated comment upsertion, the action provides continuous architectural risk assessment directly within your pull request workflow.

Composite Action Architecture and Setup

The integration is defined as a composite action in action.yml, orchestrating the entire pipeline from PyPI installation to comment posting. When triggered, the runner first installs the code-review-graph package and attempts to restore a cached SQLite graph from the .code-review-graph/ directory.

According to the source code in action.yml (lines 50-62), the setup phase uses GitHub Actions cache keys that encode the schema version (schema9) and a hash of common lockfiles. This ensures that stale caches are never restored after schema changes, preventing version mismatches between the tool and the graph database.

Base Reference Resolution

Before analyzing changes, the action determines the correct base reference for comparison. As implemented in action.yml (lines 65-77), the logic resolves origin/<base-branch> for pull requests or falls back to HEAD~1 for other events. This reference is exported as the environment variable CRG_BASE, making it available to subsequent steps.

Incremental Graph Updates vs. Full Builds

The action optimizes performance through intelligent graph management. If cache restoration succeeds, the step executes:

code-review-graph update --base "${CRG_BASE}"

This incremental update re-parses only files that differ from the PR base. On cache miss or update failure, the action falls back to a full build via code-review-graph build (Source: action.yml lines 80-88). This dual-path approach minimizes CI runtime for subsequent commits while ensuring robustness when the cache is cold.

Risk-Scored Change Detection

The core analysis occurs through the detect-changes command:

code-review-graph detect-changes --base "${CRG_BASE}"

As defined in action.yml (lines 90-95) and implemented in code_review_graph/changes.py, this command produces a JSON report containing:

• Overall risk score (0.0-1.0) calculated by compute_risk_score based on flow participation, community crossing, test coverage gaps, security-sensitive symbol names, and caller count
• Lists of changed symbols and affected execution flows
• Identification of test coverage gaps

Markdown Rendering and Risk Gating

The raw JSON report flows into scripts/render_pr_comment.py, which converts technical data into human-readable markdown. The script performs safety sanitization on symbol names and file paths before generating crg-comment.md (Source: action.yml lines 96-136).

The rendering script also implements the risk-gate functionality. When invoked with --fail-on-risk, it compares the overall risk score against the configured threshold and exits with a non-zero status if the threshold is exceeded.

Sticky PR Comment Upsertion

To prevent comment spam, the action implements a sticky comment pattern using the GitHub CLI (gh api). As detailed in action.yml (lines 105-125), the action searches for an existing comment containing the hidden HTML marker <!-- code-review-graph-report -->.

If found, the action PATCHes the existing comment; otherwise, it POSTs a new one. This ensures pull requests maintain a single, continuously-updated analysis comment regardless of how many commits are pushed.

Workflow Control and Merge Gates

When the input fail-on-risk is set to high or critical, the action enforces merge-blocking behavior. According to action.yml (lines 127-133), the rendering script exits with a failure code if the computed risk exceeds the chosen threshold, causing the GitHub workflow to fail and preventing high-risk changes from merging.

Complete Workflow Example

To integrate this into your repository, create .github/workflows/code-review-graph.yml:

name: PR Review

on:
  pull_request:

permissions:
  contents: read          # checkout

  pull-requests: write    # post comment

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on-risk: high            # optional merge gate

          comment: true                 # keep comment sticky

Local Execution for Debugging

You can replicate the action's behavior locally for testing:

# Build or update the graph

code-review-graph update --base origin/main

# Generate risk-scored analysis

code-review-graph detect-changes --base origin/main > report.json

# Render markdown with optional risk gate

python scripts/render_pr_comment.py \
  --input report.json \
  --fail-on-risk high \
  > pr-comment.md

Summary

• The composite action defined in action.yml orchestrates the entire risk-scored review pipeline without external API dependencies.
• Intelligent caching uses schema-versioned keys to restore the SQLite graph from .code-review-graph/, falling back to full builds only when necessary.
• The detect-changes command invokes compute_risk_score from code_review_graph/changes.py to calculate a 0.0-1.0 risk metric based on architectural impact factors.
• Sticky comments are maintained via the hidden marker <!-- code-review-graph-report -->, ensuring PR threads remain clean through force-pushes.
• Risk gates enable merge-blocking workflows when fail-on-risk is configured, enforcing quality standards programmatically.

Frequently Asked Questions

How does the action handle cache invalidation when the graph schema changes?

The cache key explicitly encodes the schema version (currently schema9) alongside a hash of lockfiles including package-lock.json, yarn.lock, poetry.lock, and Cargo.lock. This composite key ensures that any schema upgrade or dependency change automatically invalidates the cache, preventing restoration of incompatible graph databases (Source: docs/GITHUB_ACTION.md lines 17-24).

What permissions are required for the GitHub Action to post comments?

The workflow requires contents: read permission for repository checkout and pull-requests: write permission to create or update comments via the GitHub CLI. These permissions should be explicitly declared in the workflow file to follow the principle of least privilege.

Can the action block merging of high-risk pull requests?

Yes. When the fail-on-risk input is set to high or critical, the scripts/render_pr_comment.py script evaluates the overall risk score from detect-changes and exits with a non-zero code if the threshold is exceeded. This failure status causes the GitHub workflow to fail, which can be configured as a required status check to block merging (Source: action.yml lines 127-133).

Does the action transmit code to external services for analysis?

No. The code-review-graph action operates entirely on the CI runner using local Tree-sitter parsing and SQLite storage. All graph construction, risk scoring via compute_risk_score, and report generation execute within the repository's compute environment, ensuring source code never leaves the organization's infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}