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

> Learn to configure the GitHub Action for automated risk-scored PR reviews using code-review-graph. This action enhances your pull requests with insightful risk scores.

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

---

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

```yaml
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/.github/workflows/code-review-graph.yml) to enable automated reviews on every pull request:

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

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

```yaml
      - 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`](https://github.com/tirth8205/code-review-graph/blob/main/docs/GITHUB_ACTION.md).

### Advanced Setup with Explicit Python Version

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

```yaml
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/docs/GITHUB_ACTION.md).

### Where is the risk score calculated?

The risk score calculation resides in [`code_review_graph/changes.py`](https://github.com/tirth8205/code-review-graph/blob/main/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.