How to Configure the GitHub Action for Automated Risk-Scored PR Reviews with code-review-graph

The code-review-graph repository provides a composite GitHub Action that installs the tool from PyPI, caches the knowledge graph, and posts a sticky markdown comment with risk scores on every pull request.

The tirth8205/code-review-graph repository ships a ready-to-use composite action defined in action.yml that enables fully-local, risk-scored code reviews. By adding a single workflow file to your repository, you can automatically analyze pull requests, compute risk scores using the built-in knowledge graph, and receive detailed feedback directly in your PR thread. This guide walks you through configuring the GitHub Action for automated risk-scored PR reviews with code-review-graph, referencing the actual source implementation.

Required Permissions

Before configuring the workflow, your job must declare the correct permissions. The action needs read access to repository contents and write access to pull requests to post comments.

permissions:
  contents: read
  pull-requests: write

These permissions allow the action to read the repository source and create or update the sticky PR comment using the ${{ secrets.GITHUB_TOKEN }}. No personal access token (PAT) is required.

How the Composite Action Works

The action defined at the repository root orchestrates six distinct steps to deliver automated reviews without external services.

Installation and Environment Setup

The action uses actions/setup-python@v6 to install Python, then pulls the code-review-graph package from PyPI. You can pin a specific Python version using the python-version input, such as "3.12".

Graph Caching Strategy

To optimize performance, the action caches the SQLite knowledge graph stored in .code-review-graph/ using actions/cache@v6. If a cached graph exists, the action restores it; otherwise, it executes code-review-graph build to generate a fresh graph from the current codebase.

Change Detection and Risk Scoring

The core analysis runs code-review-graph detect-changes --base origin/<base-branch>, which identifies modified functions and impacted execution flows. Risk scores are computed in code_review_graph/changes.py within the compute_risk_score function, producing a JSON report containing per-function risk levels and test gaps.

Report Rendering and Sticky Comments

The JSON output is piped to scripts/render_pr_comment.py, a pure-stdlib Python script that converts the analysis into markdown. The script inserts a hidden HTML marker (<!-- code-review-graph-report -->) to identify its comments. On subsequent runs, the action locates the existing comment via the GitHub API and PATCHes it, keeping the PR thread clean without duplicate posts.

Risk-Based Job Gating

When you set the fail-on-risk input to high or critical, the action evaluates the overall risk level from compute_risk_score. If the risk exceeds your threshold—such as 0.70 for high—the renderer exits with a non-zero status, causing the GitHub Actions job to fail and blocking the merge.

Configuration Examples

Minimal Workflow with Sticky Comments

Add this workflow to .github/workflows/code-review-graph.yml to enable automated reviews on every pull request:

name: code-review-graph

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

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 }}

This configuration checks out the code, installs the tool, and posts a sticky comment containing the risk-scored analysis.

Enforcing Risk Gates with fail-on-risk

To block merges when risk is elevated, add the fail-on-risk input:

      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on-risk: high

Setting fail-on-risk: high aborts the job when the overall risk score reaches 0.70 or higher. Use critical for an even stricter threshold.

Fork-Friendly Setup Without Comment Posting

For pull requests from forks where write permissions are restricted, disable commenting and export the report as an artifact:

      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          comment: false

The JSON file path is exposed as the comment-file output. Upload this as an artifact for a separate privileged workflow to publish the comment later, as documented in docs/GITHUB_ACTION.md.

Advanced Setup with Explicit Python Version

Lock the Python version and use aggressive caching with this complete example:

name: code-review-graph

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

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 }}
          python-version: "3.12"
          fail-on-risk: critical

Key Configuration Inputs

The action.yml defines several inputs to customize behavior:

• github-token (required): The GITHUB_TOKEN secret with pull-requests: write scope.
• fail-on-risk (optional): Threshold to fail the job. Accepts high or critical.
• python-version (optional): Python version to use (defaults to system Python).
• comment (optional): Boolean to enable or disable PR comments (default true).

Summary

• The composite action in tirth8205/code-review-graph requires only pull-requests: write permission and actions/checkout to function.
• It caches the .code-review-graph/ SQLite database between runs using actions/cache@v6 to avoid rebuilding the knowledge graph on every PR.
• Risk scoring happens in code_review_graph/changes.py:compute_risk_score, with results rendered by scripts/render_pr_comment.py.
• The sticky comment mechanism uses an HTML marker (<!-- code-review-graph-report -->) to update existing comments rather than spamming the PR thread.
• Use fail-on-risk to gate merges based on computed risk levels (high or critical).

Frequently Asked Questions

What permissions does the GitHub Action require?

The action requires contents: read to access the repository code and pull-requests: write to post and update comments. These are satisfied by the default GITHUB_TOKEN secret in most repositories. No additional personal access tokens are needed.

How does the action handle caching?

The action caches the .code-review-graph/ directory containing the SQLite knowledge graph using actions/cache@v6. On subsequent runs, it restores this cache; if the cache misses, it automatically runs code-review-graph build to reconstruct the graph from the current codebase.

Can I use this action on forks or external contributions?

Yes, but you must handle permissions carefully. Set comment: false to skip posting comments directly, then export the comment-file output as an artifact. A separate workflow with appropriate permissions can read this artifact and post the comment, circumventing the write permission restrictions on fork PRs as described in docs/GITHUB_ACTION.md.

Where is the risk score calculated?

The risk score calculation resides in code_review_graph/changes.py within the compute_risk_score function. This function analyzes the detected changes against the knowledge graph to produce per-function risk scores and identify affected execution flows, which the action then surfaces in the PR comment.

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