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

> Discover how the code-review-graph GitHub Action provides risk-scored PR reviews. Learn how it builds a knowledge graph and calculates a risk score for your pull requests directly on the CI runner.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

```bash
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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

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

```

As defined in [`action.yml`](https://github.com/tirth8205/code-review-graph/blob/main/action.yml) (lines 90-95) and implemented in [`code_review_graph/changes.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/crg-comment.md) (Source: [`action.yml`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/.github/workflows/code-review-graph.yml):

```yaml
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:

```bash

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.