@xpert-ai/plugin-code-review
v0.7.0
Published
Version-aware pull request review and findings workspace for Xpert
Readme
Code Review
Installable Xpert app and composable Code review Assistant capability for GitHub PR review and workflow failure diagnosis. Built with Shadcn UI + Tailwind CSS. Includes immutable diff snapshots, private AI findings, viewed files, checks, repository policies, a review inbox, and governed GitHub submission.
See automatic PR review setup, setup and usage, architecture, and validation.
Project type
Create a Code Review Project before configuring a review pipeline. Its stable identity is applicationKey: @xpert-ai/plugin-code-review:code-review, projectTypeKey: review. New Code Review Assistants declare this default project type. PR, lightweight PR and local Git pipeline templates explicitly target this type; they are unavailable in BOM and general projects.
The platform and plugin must be upgraded together to the pipeline contract with required template.projectTypes. There is no migration or fallback for old project classifications or saved configurations: create a new Code Review Project and save a new pipeline configuration. Template discovery, configuration saving and pipeline startup validate the project's persisted type on the server.
Review workbench
The compact toolbar opens GitHub PRs and local Git imports from New review. Navigation, the PR queue, and the selected review occupy independently scrolling panes. The navigation and queue can be collapsed for narrow Workbench panels.
The queue combines authorized manual reviews and webhook runs into one row per GitHub PR. Agent child reviews are excluded; Run history exposes the authorized root records and their fixed commit versions. Search, repository/status filters, selection and detail tabs are retained through Workbench navigation parameters. An event that was skipped remains inspectable even when no review snapshot exists.
Open review pipeline and Open approval navigate inside the host Workbench with the saved Project, pipeline instance and round identifiers. Approval and publication remain governed by the existing pipeline. Repository access rules and historical private-run boundaries are unchanged.
Configure automatic reviews
Automatic reviews require a configured GitHub App, an authorized account connection and enabled repository rules. Choose Current Assistant for PR review through the bound Assistant, or Project pipeline for governed review and publication. Workflow failure/timeout diagnosis can be enabled in either PR mode and always uses the bound Assistant. Enable GitHub events · Code review in that Assistant's Automation tab for Assistant reviews and diagnoses. Existing rules retain their mode; new rules default to Current Assistant. Saving the plugin configuration alone does not enable automatic reviews.
Supported events
| GitHub event | Trigger | Execution |
| --- | --- | --- |
| pull_request | opened or reopened | Current Assistant or Project pipeline |
| pull_request | ready_for_review | Current Assistant or Project pipeline |
| pull_request | synchronize (new commits, with a 30-second wait) | Current Assistant or Project pipeline |
| workflow_run | completed with failure or confirmed timeout | Bound Assistant, alongside either PR mode; no PR required |
Enable each condition in the repository rules. Draft PRs are skipped, and bot-authored PRs are excluded unless enabled. Branch filters match exact PR base branches or Workflow run branches; Workflow names also match exactly. Empty filters include all values. PR updates use pull_request.synchronize, not a separate push subscription.
Issues, comments, review requests, standalone push events, releases, check runs/suites and PR closing/merging do not start tasks. Successful or skipped workflows and ordinary cancellations do not start diagnosis. Cancelled runs require job-bound timeout evidence before diagnosis; see timeout handling. Subscribing to additional GitHub events does not add plugin support for them.
1. Install and initialize
- Install
@xpert-ai/plugin-code-reviewat its declaredsystemlevel, using tenant scope in the Default tenant. - Initialize Code Review from the application catalog with an existing, available model. Confirm that the generated Assistant is published and can run.
- Install
@xpert-ai/plugin-github-connectorin the application's organization to connect users' GitHub accounts. Select the plugin installation scope separately from the application's organization and workspace scope. - Provide a public HTTPS API origin, such as
https://api.example.com, that GitHub can reach. Route the webhook path below to the Xpert backend. GitHub cannot deliver events directly tolocalhost.
For manual viewing and AI review of public PRs, you can leave the plugin configuration empty. Private repository access and manual GitHub review submission still require a GitHub connection in the current workspace.
2. Set up the GitHub App
In your GitHub account or organization, open Settings → Developer settings → GitHub Apps and create or edit the App for automatic reviews.
Record the numeric App ID from its settings page and the actual
<slug>from its public URL,https://github.com/apps/<slug>.Generate and download a PEM private key through Credentials → Key pairs → New key. Older interfaces may show Private keys → Generate a private key. See Managing private keys for GitHub Apps.
Under Webhooks, select Active and enter the complete Webhook URL:
https://api.example.com/api/code_review/github/webhookReplace the example domain with your public API domain. For webhook-triggered reviews, create a random Webhook secret of at least 32 characters and enter the same value in GitHub and the GitHub system integration. You can leave the secret empty to save the integration while preparing setup, but webhook deliveries will be rejected until a secret is configured. To generate a 64-character secret locally:
openssl rand -hex 32Under Repository permissions, set Contents: Read-only and Pull requests: Read & write. Under Subscribe to events, select Pull request. For workflow failure/timeout diagnosis, also grant Actions: Read-only and subscribe to Workflow run. Timeout diagnosis additionally requires Checks: Read-only.
Use Install App to install the App on the target account or organization and grant access to the repositories you want to review.
3. Configure one GitHub system integration
Open Settings → System Integration at tenant scope in the Default tenant where the system plugin is installed. Create or edit a github integration for this App:
| Integration option | Value |
| --- | --- |
| appName | A display name for the App. |
| appSlug | The lowercase URL identifier from https://github.com/apps/<slug>, not the display name. |
| appId | The numeric GitHub App ID, not the Client ID or Installation ID. |
| clientId / clientSecret | The same App's OAuth Client ID and Client Secret. |
| privateKey | The complete PEM contents, including the BEGIN/END lines; not a file path. |
| webhookSecret | The same secret configured in GitHub, at least 32 characters. Optional while preparing setup; required to accept webhook events. |
Configure the App's User authorization callback URL as https://api.example.com/api/connector/oauth/callback and its Webhook URL as https://api.example.com/api/code_review/github/webhook. Set the host's API_BASE_URL to the public API origin. OAuth authorization and App installation are different grants for this one App.
Then open Plugins → Code Review → Configuration and select that GitHub system integration. The plugin stores only this reference:
{
"githubIntegrationId": "00000000-0000-4000-8000-000000000001"
}Replace the example UUID with the integration selected in the UI. All organizations using this system plugin must belong to its installation tenant; organization-scoped and other-tenant integrations are not eligible. An unavailable or incomplete selected integration stops automatic reviews; the plugin never searches for a replacement.
The integration may be saved without a webhook secret, but signed and unsigned webhook deliveries are both rejected until a secret is configured. Blank secret fields on an existing integration preserve the saved value; enter a new value to rotate it. Credentials are resolved again for each operation, so key/secret rotations do not require copying them into the plugin. Never commit credentials to source control.
On hosts supporting PluginContext.readConfig(), Code Review reads its selected integration reference from the database whenever App configuration is needed. This keeps API replicas consistent without background configuration polling. Database or configuration errors stop the operation; they do not fall back to an old reference. Older hosts retain the local configuration snapshot behavior, so deploy the matching platform update to enable this behavior on every replica.
4. Connect repositories and enable rules
- In Code Review, open Connect repositories and click Connect GitHub. Complete the platform's OAuth dialog, which is pinned to the selected system integration. Automatic repository setup requires GitHub App OAuth from that integration. PATs remain available for manual connector use. The current connection is shared within the workspace.
- Confirm that the connected account has write or admin permission on the target repository and that the GitHub App is installed with access to it. The account connection verifies the user's repository permissions; the App installation receives events and publishes reviews. Both are required.
- Enter
owner/repository, click Add repository, and open Configure rules. - Enter the number of an existing open, non-draft PR and click Try review (no publishing). Trials consume model usage and save results privately without publishing to GitHub.
- Inspect the trial result, select Enable automatic reviews, configure triggers, base branches, ignored paths, additional review guidance and the daily limit, then save the rules.
- For Current Assistant, enable GitHub events · Code review in its Automation tab; new automatic results follow Assistant access. For Project pipeline, bind a valid Code Review Project pipeline. In either mode, choose PR review publication in the repository rules. Select Automatically comment on GitHub PRs to post the final summary and findings as a
COMMENTreview, including reports that require rework. This action only posts comments. You can also keep reports in Xpert or require confirmation. Workflow diagnosis is independently enabled in either mode and retains Assistant access and the Assistant trigger requirement.
Automation starts paused. Existing Current Assistant rules default to saving reports in Xpert and Project pipelines default to confirmed publication. Once enabled, the default triggers cover opened or reopened PRs, drafts marked ready for review, and new commits. Draft and bot-authored PRs are excluded by default. The default daily limit is 20 attempts per repository per UTC day, shared by PR reviews, trials and Workflow diagnosis.
5. Verify the setup
App parameters configured only means that the saved App configuration can be parsed. It does not validate credentials, repository installation, event subscriptions or webhook connectivity; it can be shown before a Webhook secret is set. The displayed Webhook URL is generated from the current API address, not read back from GitHub. Local tests also need a public HTTPS endpoint, such as a tunnel to the backend; update GitHub when its address changes. Configure the OAuth callback separately.
A PR trial verifies review execution, not webhook delivery or automatic triggering. For Current Assistant, publish its Code Review capability and enable both the repository rule and GitHub events · Code review in the Assistant's Automation tab. Project pipeline mode requires a valid pipeline binding and enabled repository rules.
PR acceptance: trigger one of the enabled PR actions, then check GitHub delivery history, the review inbox and run history.
Workflow acceptance: in either PR mode, grant Actions: Read (and Checks: Read for timeouts), subscribe to Workflow run, and enable the failure or timeout rule and the Assistant's GitHub trigger. Run a safe failing test workflow or redeliver a matching completed failure/timeout event. Check GitHub delivery history, the Assistant task and Workflow diagnosis. Duplicate deliveries are deduplicated and may not create another run.
Check the GitHub App's webhook delivery history to confirm that requests reach the configured URL. The plugin returns HTTP
202for valid deliveries. This confirms webhook handling, not completion of the model review or comment publication.In Code Review, check the repository's Last event timestamp and inbox records, then inspect the trial or event-triggered review result. New-commit events wait at least 30 seconds to combine consecutive pushes.
If setup fails, check the integration reference, its App ID, lowercase slug, complete PEM, OAuth credentials and secret length. An existing connection with another integration, a PAT, or no recorded OAuth application identity must be disconnected in workspace connector settings and reauthorized using Connect GitHub. This shared connection is never silently replaced. For signature errors, configure matching webhook secrets in GitHub and Xpert and verify that the host retains
request.rawBodyfor signature verification.If a repository cannot be added, check the GitHub account connection, the user's write/admin permission, the App's repository access and its permissions separately. If events arrive without a review, check whether rules are enabled, branch filters, draft or bot-authored PR status, daily quota, and Assistant and model availability.
Repository binding conflicts disclose a separate, read-only ownership summary after the platform's Assistant edit check and live GitHub write/admin and App installation checks pass. Within a tenant it includes the organization, original configurer, current maintainer, first configuration time and automation status. The bound Assistant is shown only after its own live access check. Other-tenant conflicts disclose only the verified repository name and guidance to contact a platform administrator. This does not grant access to rules, private review history, rebinding or migration across organizations.
For upgrades, run migrations/20261105-repository-conflict-labels.sql against the host database to fill missing organization/actor display names in existing plugin audit snapshots. It is replayable, preserves recorded names and does not change bindings or execution revisions. New configuration audits capture the organization name automatically. Names are recorded labels, not a live directory; legacy records without audit evidence or deleted identities display their identifier with “Name not recorded” so an administrator can reconcile them. No cross-tenant identifiers or labels are returned.
After building, node scripts/repository-conflict-acceptance.mjs exercises the built iframe and bridge with synthetic organization, Assistant, tenant, legacy and denied-access conflicts, successful retry and context changes. Set XPERT_TEST_CHROMIUM to an installed Chromium executable when needed; PREVIEW_LOCALE=en PREVIEW_THEME=dark covers the English dark theme, and XPERT_TEST_SCREENSHOTS optionally saves screenshots. These fixtures do not call GitHub or replace deployment acceptance.
See Automatic PR review for publication behavior, queue requirements and failure recovery.
Code Review resolves the configured integration through the built-in
INTEGRATION_PERMISSION_SERVICE_TOKEN and IntegrationPermissionService.readConfiguration(id).
The host checks the plugin's declared access and configuration tenant/organization scope.
Code Review validates the returned GitHub identity and retains its review execution scope
checks. Webhook payloads never select the configuration scope. No plugin-specific CQRS
query is required.
The Connect GitHub action requests the generic workspace.connector.connect
command with provider: 'github', authMethodId: 'github-app-oauth', and the configured
integrationId. The platform validates the Connector's declared capabilities and
pins the authorized method and integration in its dialog. GitHub-specific method
selection and error guidance belong to this plugin; the host supports the same
constraints for other Connectors, including API key methods. An active or pending
shared connection with different credentials must be resolved explicitly in the
workspace Connector settings.
Upgrade from inline GitHub App configuration
- Upgrade the platform (host configuration-read capability, system integration schema and host connection dialog), then GitHub Connector and Code Review. The new reference mode requires these host capabilities; upgrading only the plugins is insufficient.
- Before starting the upgraded plugin against an existing database, apply
20261021-github-system-integration.sql, or let the host synchronize the two nullable repository columns. The migration is idempotent and does not backfill an identity. - Copy the legacy App values into the intended GitHub system integration, including the OAuth credentials for that same App. Select it in Code Review configuration. Saving the selection removes the legacy
githubAppcopy. Legacy configuration remains supported only until a reference is selected; an invalid reference never falls back to it. - Reauthorize the shared Connector if prompted. The connector records the integration and OAuth Client ID from the actual authorization. Changing the integration's Client ID invalidates that proof even if its integration ID stays the same.
- Open each existing repository's rules and save with automation enabled to revalidate its installation and pin the integration and App ID. Pending runs from the previous policy revision are cancelled; trial/retry creates a run using the current binding. Changing App identity requires revalidation; switching to a different installation requires an explicit ownership migration.
- Redeliver a GitHub event and inspect the review inbox. The webhook endpoint and one-owner-per-installation/repository rule remain unchanged. Rotate webhook secrets in GitHub and System Integration together; events signed with the previous secret are rejected.
For rollback, pause automatic reviews first, retain the additive database columns, and restore a compatible plugin configuration and Connector authorization. No automated migration or rollback copies secrets between tenants.
Build and test
Code Review requires published @xpert-ai/contracts and @xpert-ai/plugin-sdk
3.26.1 or newer for the Project Pipeline API, host configuration reads and pinned integration connect contracts. Deploy the matching platform and GitHub Connector for reference mode. Development dependencies are pinned
to 3.26.1 in the workspace lockfile. No adjacent platform checkout or local SDK
link is required.
From the repository's xpertai/ directory:
corepack pnpm install --frozen-lockfile
corepack pnpm exec nx build @xpert-ai/plugin-code-review
corepack pnpm --filter @xpert-ai/plugin-shadcn-ui build
corepack pnpm exec nx run-many -t typecheck,test,verify:dist -p @xpert-ai/plugin-code-review --parallel=1The authorization tests import the shared UI bridge, so its workspace package must be built before testing in a clean checkout.
Set XPERT_PIPELINE_TEST_DATABASE_URL to a dedicated PostgreSQL test database
whose name starts with xpert_pipeline_test_ to run persistence, scope enforcement,
and delivery tests. Without it, those tests are skipped. Tests create isolated
schemas and remove them on completion. Verify the built plugin's lifecycle
locally by following plugin-dev-harness.
Run node apps/code-review/scripts/automation-acceptance.mjs with the same dedicated database URL for signed webhook ingestion, real App/Connector resolution, single-owner routing and publication checks against fixture GitHub/model transports.
Install with the platform plugin:deploy:local command. Initialize the application from the catalog with an existing model. Public PR reads need no connector; private repositories and GitHub submission require the scoped GitHub connector.
Host configuration-read capability
Integration references require the host's integration.readConfiguration(id) capability.
The host binds it to the plugin installation scope, checks declared integration access
and resolves system configuration in the Default tenant. Code Review supplies only the
Integration ID and does not require configuration-tenant metadata in PluginContext.
Upgrade the host before this plugin. If the capability is unavailable, configuration
references fail closed; they never fall back to the legacy read(id) lookup. Legacy
inline App configuration remains supported during migration.
Repository pipeline routing
Repository rules explicitly select Current Assistant or Project pipeline for PR execution. Workflow diagnosis remains an independent Assistant path in both modes; switching PR modes preserves its settings. Pipeline evidence follows Project access and new diagnoses follow Assistant access. Existing private evidence is unchanged. See automation setup and governance. The code-review Assistant capability can be enabled during blank creation or profile editing, and exposes review tools plus the gated workbench.
For Assistant automation, configure authorized repositories and event filters in Code Review, then enable GitHub events · Code review in the Assistant's Automation tab. This subscription runs on the server independently of Bosi. It supports PR opened/reopened/ready/synchronize and failed or timed-out workflow_run.completed events. Workflow diagnosis additionally requires Actions: Read and the Workflow run event subscription on the GitHub App. No GitHub publication or code execution is performed by diagnosis tools.
Apply migrations/20261102-assistant-events.sql after the existing migrations when schema synchronization is externally managed. It adds subscription/diagnosis records and request idempotency, preserves old pipeline policies, and does not change sharing or subscribe existing Assistants. See setup, templates and migration.
The new trigger status projection requires the matching host SDK/server change (IWorkflowTriggerStrategy.assistantStatus and trusted validation/publication scope). Development uses the exact host build as described below; publishing requires a released SDK containing those contracts. The existing registry range alone does not prove compatibility with these new host features.
With a disposable xpert_pipeline_test_* PostgreSQL database, run scripts/assistant-events-acceptance.mjs in addition to the pipeline acceptance. It exercises signed ingestion, duplicate deliveries, private ownership, task finalizers, ambiguous dispatch recovery, workflow attempts, pause/revocation, PR-link idempotency and additive migration. GitHub and model transports are fixtures; real public ingress and provider permissions require separate deployment verification.
Personal App installation / 个人安装
The App declares scope: ['organization', 'personal']. On an upgraded Xpert host, an active organization member can enable a private instance through Only me; organization installation remains available to administrators. Plugin code is still deployed at its original native level. Explicit Project/Assistant sharing retains its existing authorization rules.
应用支持在当前组织内为自己安装独立实例,也保留管理员的组织安装入口。个人安装不会复制或共享其他用户的授权凭据。升级宿主后再启用数组形式的 scope,旧宿主不保证支持此声明。
For development against the unreleased host change, build its public contracts/SDK, then bind this plugin without changing registry lockfiles (run from the xpert-plugins root):
node scripts/use-platform-packages.mjs /path/to/xpert xpertai/apps/code-reviewBuild and run plugin-dev-harness against that same host version. Registry dependency versions must be updated to the released contracts/SDK containing this capability before publishing the plugin. To restore the registry development dependencies, run corepack pnpm install --force in xpertai.
