#GitHub Action Integration

Rsdoctor provides an official GitHub rsdoctor-action for easy integration of Rsdoctor analysis functionality in CI/CD workflows. Through GitHub Action, you can automatically perform bundle diff analysis on the build output and monitor and prevent bundle degradation, continuously optimizing project performance.

#Quick Start

#Step 1: Install Rsdoctor Plugin in Your Project

1. Follow the Quick Start guide to install the Rsdoctor plugin in your project and configure it according to your project type.

2. You need to use Brief mode and add 'json' to the type array so that the analysis data can be uploaded in the subsequent GitHub Action. For detailed configuration, see output options.

• Example below, Rsbuild integration example:

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    rspack: {
      plugins: [
        new RsdoctorRspackPlugin({
          output: {
            mode: 'brief',
            options: {
              type: ['json'],
            },
          },
        }),
      ],
    },
  },
});

#Step 2: Configure GitHub Workflow

Create a .github/workflows/ci.yml file in your GitHub repository as shown in the example below. Please note the following points:

• file_path: Required, path to the Rsdoctor JSON data file.
• target_branch: Optional, target branch name, defaults to 'main'. If you want to use a dynamic target branch, i.e., automatically get the target branch of the current pull request instead of a fixed main branch, you can use the following configuration:

target_branch: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || github.event.repository.default_branch }}

• dispatch_target_branch: Optional, used to specify the target branch when manually triggered (workflow_dispatch).

• AI_TOKEN: Optional, used to enable AI-assisted bundle degradation analysis. Configure it as a GitHub Actions secret and pass it to the action step through env.

• ai_model: Optional, AI model used for degradation analysis. The default is claude-3-5-haiku-latest. The provider is automatically detected from the model name prefix. Supported prefixes include claude, gemini, deepseek, and qwen; other model names use the OpenAI provider.

• on indicates when the workflow runs, commonly set to pull_request and push, and also supports workflow_dispatch for manual triggering.

  • On pull_request, Rsdoctor Action fetches baseline and current and performs bundle diff analysis.
  • On push (i.e., after PR merge), it updates and uploads the baseline.
  • workflow_dispatch allows you to manually trigger the workflow from the GitHub Actions page. This mode combines the behavior of push and pull_request: it uploads baseline data, and if dispatch_target_branch is specified, it also performs baseline comparison analysis.

• Before executing rsdoctor-action, build your project with the Rsdoctor plugin enabled to generate the Rsdoctor JSON data file.

name: Bundle Analysis

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches:
      - main # or your target branch name
  workflow_dispatch: # Optional, allows manual triggering
    inputs:
      target_branch:
        description: 'Target branch to compare against'
        required: false
        default: 'main'
        type: string

jobs:
  bundle-analysis:
    runs-on: ubuntu-latest

    permissions:
      # Allow commenting on commits
      contents: write
      # Allow commenting on issues
      issues: write
      # Allow commenting on pull requests
      pull-requests: write
      # Allow reading workflow runs and downloading artifacts for baseline comparison
      actions: read

    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Pnpm
        run: |
          npm install -g corepack@latest --force
          corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: 22
          cache: 'pnpm'

      - name: Install Dependencies and Build
        run: |
          pnpm install
          pnpm run build

      - name: Bundle Analysis
        uses: web-infra-dev/rsdoctor-action@main
        env:
          # Optional. Required only when you want AI-assisted analysis.
          AI_TOKEN: ${{ secrets.AI_TOKEN }}
        with:
          file_path: 'dist/.rsdoctor/rsdoctor-data.json'
          # Default 'main'. If you want to use a dynamic target branch, i.e., automatically get the target branch of the current pull request instead of a fixed main branch, you can use the following configuration:
          # ${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || github.event.repository.default_branch }}
          target_branch: 'main'
          # Target branch for manual trigger
          dispatch_target_branch: ${{ github.event.inputs.target_branch }}
          # Optional. Defaults to 'claude-3-5-haiku-latest'.
          ai_model: 'claude-3-5-haiku-latest'

#AI-assisted analysis

Rsdoctor Action can use AI to summarize bundle degradation in pull requests and workflow summaries. AI-assisted analysis runs only when baseline data exists and the bundle size changes. To enable it, add an AI provider token as a repository secret and pass it to the action step:

1. Open your GitHub repository, then go to Settings -> Secrets and variables -> Actions.
2. Create a repository secret named AI_TOKEN.
3. Pass the secret to rsdoctor-action with env.AI_TOKEN.
4. Optionally set ai_model if you want to use a model other than the default claude-3-5-haiku-latest.

- name: Bundle Analysis
  uses: web-infra-dev/rsdoctor-action@main
  env:
    AI_TOKEN: ${{ secrets.AI_TOKEN }}
  with:
    file_path: 'dist/.rsdoctor/rsdoctor-data.json'
    target_branch: 'main'
    ai_model: 'claude-3-5-haiku-latest'

If AI_TOKEN is not provided, the Action still runs the regular bundle diff analysis, but AI-assisted analysis will be skipped. The token must match the provider detected from ai_model. For example, use an Anthropic token with claude-*, a Google token with gemini-*, a DeepSeek token with deepseek-*, a Qwen token with qwen*, or an OpenAI token with OpenAI model names such as gpt-4o-mini.

#View Reports

After submitting the above configuration file to your repository, GitHub Actions will automatically run under the specified trigger conditions and generate Rsdoctor analysis reports. You will see bundle size change comparison prompts in GitHub CI, as shown below:

Additionally, clicking "Download Bundle Diff Report" allows you to download Rsdoctor's diff report for detailed diff data viewing.

For detailed Bundle Diff report content, see Bundle Diff Usage Guide.

#Troubleshooting

#Common Issues

Q: Action fails with "❌ Rsdoctor data file not found"

• Ensure your build process generates Rsdoctor JSON data, the default path is /rsdoctor-data.json.
• Check if file_path points to the correct location
• Verify that the Rsdoctor plugin is properly configured in your build tool

Q: If you see the message "No baseline data found", what does it mean?

• This is normal for the first run or for new repositories, because no baseline has been uploaded yet. The baseline data will be created after the first merge into the main branch.

Q: AI-assisted analysis is not shown

• Ensure the AI_TOKEN secret has been created in repository settings and passed to the action step through env.
• Check whether the selected ai_model matches the provider token. The provider is detected from the model name prefix.
• Confirm that baseline data exists and the bundle size changed in the current run.
• For pull requests from forks, GitHub may not expose repository secrets to the workflow for security reasons.

#More Resources

• rsdoctor-action GitHub Repository
• Rsdoctor AI Guide