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

The millionco/react-doctor repository ships a composite GitHub Action (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, 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. 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:

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, 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 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 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.

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