# React Doctor GitHub Actions Integration: How It Automatically Posts and Updates PR Comments

> Integrate React Doctor with GitHub Actions to automatically post and update PR comments. Streamline your code review process with automated diagnostics directly in your pull requests.

- Repository: [Million Software, Inc./react-doctor](https://github.com/millionco/react-doctor)
- Tags: how-to-guide
- Published: 2026-05-12

---

**The `millionco/react-doctor` repository ships a composite GitHub Action ([`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml)) that executes the `react-doctor` CLI, captures structured diagnostics to a temporary file, and uses `actions/github-script@v7` to create or update a marked PR comment whenever a valid `github-token` is provided on `pull_request` events.**

The `millionco/react-doctor` toolchain streamlines code review by embedding diagnostic results directly into pull requests via a self-contained GitHub Actions integration. Defined entirely in the root [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml), this composite action orchestrates CLI execution, numeric score extraction, and idempotent comment management without external services. Its marker-based upsert logic ensures that repeated workflow runs modify a single persistent comment rather than spamming the PR with duplicates.

## Core Workflow of the Composite Action

The React Doctor GitHub Actions integration operates through a strictly ordered sequence defined in [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml). Each phase handles a discrete responsibility: CLI diagnostics, score calculation, or comment persistence.

### Phase 1: Executing the CLI with Output Capture

The action invokes the latest `react-doctor` release via `npx -y react-doctor@latest`, assembling flags from user inputs including `directory`, `verbose`, `project`, `diff`, `offline`, and `fail-on`. Standard output is redirected to a temporary file located at either `$RUNNER_TEMP` on GitHub-hosted runners or `/tmp` otherwise, with the exact path exported as the `REACT_DOCTOR_OUTPUT_FILE` environment variable for downstream consumption【/cache/repos/github.com/millionco/react-doctor/main/action.yml#L70-L78】.

### Phase 2: Calculating the Numeric Score

A dedicated step runs `react-doctor --score --fail-on none` (appending `--offline` when specified) to generate a quantitative maintainability metric. The resulting integer is stored in the GitHub Actions output `steps.score.outputs.score`, making it available for conditional logic or badge generation in subsequent workflow steps【/cache/repos/github.com/millionco/react-doctor/main/action.yml#L92-L101】.

### Phase 3: Idempotent PR Comment Management

When the workflow triggers on a `pull_request` event and receives a valid `github-token`, the action loads `actions/github-script@v7` to execute an inline Node.js script. This script performs three distinct operations:

1. **Marker detection**: It queries the GitHub API via `github.rest.issues.listComments` to locate any existing comment containing the hidden marker `` `<!-- react-doctor -->` ``.
2. **Body assembly**: The script reads the diagnostic output from the file at `REACT_DOCTOR_OUTPUT_FILE`, wraps it in a fenced code block, and prepends the optional score line `` `**Score:** \`<score>\` / 100` `` when data is present.
3. **Upsert execution**: Depending on whether the marker was found, the script either updates the existing comment using `github.rest.issues.updateComment` or creates a new one via `github.rest.issues.createComment`【/cache/repos/github.com/millionco/react-doctor/main/action.yml#L104-L145】.

This marker-based approach guarantees that repeated workflow runs modify the same comment anchor, keeping PR threads clean across multiple pushes.

## Required Workflow Configuration

To enable PR comments, the consuming workflow must supply two critical elements: the `github-token` input and appropriate job permissions.

### Token and Permissions

The `github-token` input must receive a token with `pull-requests: write` scope, typically `${{ secrets.GITHUB_TOKEN }}`. The job definition must explicitly declare `permissions: pull-requests: write`. Without these credentials, the action silently skips comment posting and logs results only to the workflow console.

### Complete Workflow Example

The following YAML implements the recommended setup for running React Doctor on pull requests and pushes to `main`, including the `fetch-depth: 0` requirement necessary for the `--diff` flag to function:

```yaml
name: React Doctor

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write   # required to post PR comments

jobs:
  react-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # needed for `--diff`

      - uses: millionco/react-doctor@main
        with:
          diff: main                     # scan only changed files

          github-token: ${{ secrets.GITHUB_TOKEN }}

```

## Summary

- **Composite action architecture**: The entire integration lives in [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml), combining shell steps for CLI execution with JavaScript snippets for GitHub API interaction.
- **Marker-based idempotency**: The action locates previous comments via the `` `<!-- react-doctor -->` `` marker, ensuring updates replace creation on subsequent runs.
- **Environment-driven communication**: Temporary files (`REACT_DOCTOR_OUTPUT_FILE`) and step outputs (`steps.score.outputs.score`) pass data between shell and Node.js execution contexts.
- **Scoped permissions**: PR comments require explicit `pull-requests: write` permission and a valid `github-token` provided on `pull_request` events.
- **External dependencies**: The implementation relies on `actions/github-script@v7` for authenticated API calls and `npx` for runtime CLI installation.

## Frequently Asked Questions

### How does the action prevent duplicate comments on the same PR?

The Node.js script embedded in [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml) iterates through existing comments using `github.rest.issues.listComments`, searching for the unique HTML marker `` `<!-- react-doctor -->` ``. If detected, the script updates that specific comment via `github.rest.issues.updateComment`; otherwise, it creates a new one using `github.rest.issues.createComment`. This logic ensures a single persistent comment per pull request regardless of how many times the workflow runs.

### What permissions are required for the GitHub token?

The workflow job must declare `permissions: pull-requests: write`, and the provided `github-token` must have scopes allowing comment creation and modification on the target repository. When these permissions are absent, the action executes the diagnostic silently without attempting to post or update PR comments.

### Can I customize the diagnostic criteria used in the action?

Yes. The [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml) exposes standard CLI flags—including `directory`, `verbose`, `project`, `diff`, `offline`, and `fail-on`—as workflow inputs. These map directly to `react-doctor` command-line arguments, allowing you to tailor scan scope, error thresholds, and output verbosity without forking the action source.

### Where is the diagnostic output stored before posting to the PR?

During execution, the CLI output is written to a temporary file at a path stored in the `REACT_DOCTOR_OUTPUT_FILE` environment variable, which resolves to `$RUNNER_TEMP` on GitHub-hosted runners or `/tmp` in self-hosted environments. The `actions/github-script` step subsequently reads this file to construct the final markdown comment body.