Skip to content

Separate-site Server installation

Install this module on the Server Drupal site. AI Code Review UI is installed on another Drupal site and connects with a service token. Use HTTPS and the PHP extensions/runtime dependencies declared by Composer. Install Drush in the host Drupal project if it is absent; Composer exposes the queue executable as vendor/bin/run-review-worker.php after package installation.

The Server worker requires Linux with a mounted, readable /proc filesystem for production Git process-tree containment and memory checks. PHP extensions alone are insufficient. This requirement applies to the Server worker, not the separate UI site.

Install the module package

In the Server site's Composer project, install the current development package:

composer require drupal/ai_code_review_server:1.x-dev

The first alpha release is being prepared. After publication, use composer require drupal/ai_code_review_server:1.0.0-alpha1 to select it explicitly. Development metadata currently uses Composer source fallback rather than a Composer distribution archive. Review the package requirements in composer.json: PHP >=8.4, Drupal ^11.4 || ^12, and the declared extensions and libraries. The common UI/Server test configuration uses Drupal 11.4 and PHP 8.4; the Server's Drupal 12 declaration does not extend the UI's declared Drupal compatibility.

Complete the protected storage and authentication setup below before enabling review execution. The first alpha is for evaluation; no model is designated as a quality-accepted recommendation.

Trusted source helper permissions

Verify the module source before preparing its permissions. A raw GitLab source archive may preserve group-writable mode 0775; it is not an accepted official Drupal Composer distribution. Setting umask 0022 affects future file creation, not existing archive permissions. The fixed bin/git-askpass.php helper must be a regular executable file, not a symlink, with no group or world write permission. Its bin parent must also be a non-symlink directory.

From the root of the verified trusted module copy, restore only this helper:

test -d ./bin &&
  test ! -L ./bin &&
  test -f ./bin/git-askpass.php &&
  test ! -L ./bin/git-askpass.php &&
  chmod 0755 ./bin/git-askpass.php

This fixed-path command is for the trusted module, not untrusted review repositories. Do not apply recursive permission changes. The runtime validator continues to reject an invalid or group/world-writable helper.

Before enabling the module

Web requests, worker and cron must use the same site, writer identity and local Entity lock directory on one host. NFS and multiple-host locking are unsupported. Provision an existing canonical local directory outside the web root, uploads, review workspaces and secret directories. Its effective writer UID must own it, it must be writable with mode 0700, and its parents must resist replacement. Share that exact path/mount with all writers. Do not recreate the directory or unlink its lock files while any writer is active.

Add the following required parameters to the site's protected services.yml; the path and account name are examples, not operational defaults:

parameters:
  ai_code_review_server.entity_lock_directory: /var/lib/ai-code-review-locks
  ai_code_review_server.entity_storage_account_name: ai_code_review_storage

Enable with vendor/bin/drush en ai_code_review_server, then create a real active, non-UID1 account matching the configured storage name. Give it a non-administrator role granting only manage ai code review internal records. Never grant that permission to API client accounts or general roles. The module does not create accounts; persistence remains unavailable until this account is ready. Verify lock contention between all writer processes before operation.

Authentication and provider registration

Configure service-token authentication. Map each client to its own active Server account with access ai code review server api and, when the UI manages its profiles, manage ai code review provider profiles. If the UI sends review criteria, also grant submit ai code review policies to that account; otherwise select None in the UI. Administrative settings use the separate administer ai code review server permission. No role is granted these permissions automatically.

Inject these independent secret settings through the site's protected settings or secret manager, never through exported configuration, source, logs or images:

Setting Required contents
ai_code_review_server.authentication Client secret hashes and account mapping described in the authentication guide.
ai_code_review_server.provider_registration current_key_id, and keys mapping key IDs to base64 libsodium crypto_box secret keys.
ai_code_review_server.provider_credential_encryption current_key_id, and keys mapping key IDs to base64 32-byte libsodium secretbox keys.

Use separate keys for the two purposes; retain required previous key versions while stored credentials still reference them. Protect the DB and backups that contain review contents and encrypted provider records. Review input/results do not require an application-level job encryption key.

For a direct_server deployment, register an owner-scoped profile through the advertised capabilities/envelope protocol, then select its provider_profile_id in review requests. Keep gateway_base_url empty and enable the service at /admin/config/services/ai-code-review-server. APISIX, its URL/HMAC identity, provisioner TLS/idempotency files and dummy gateway values are not prerequisites for direct-only operation. Provider credentials are decrypted only in the direct transport for the selected provider call. Managed APISIX profile registration is not enabled by this installation path.

APISIX execution instead requires a valid gateway origin and matching ai_code_review_server.apisix_hmac settings (key_id, secret) plus a separately configured gateway. Do not insert dummy signing credentials to enable direct execution. Python analysis is disabled by default; enabling it requires its separately deployed, protected Unix-socket sidecar and validated policy.

Review execution switch

The boolean ai_code_review_server.settings:enabled defaults to false. Only boolean true enables review execution; a missing, false or invalid value fails closed. Enable it at /admin/config/services/ai-code-review-server after configuring the selected route. A direct-only deployment keeps the APISIX URL empty and needs no APISIX signing identity.

Service-token authentication and the route's API permission run first. While disabled, an authenticated and permitted POST /api/ai-code-review/v1/reviews returns canonical 503 service_unavailable, before request admission, profile resolution, idempotency acceptance or Job/delivery allocation. Retrying an existing idempotency key also receives that response; use its accepted review's status/result resource instead. Status and retained-result reads, cancellation and provider capabilities/registration/rotation/reads/revocation keep their existing operation-specific authentication, permissions, ownership and retention conditions. This flag controls review execution, not those other operations.

Workers refresh active configuration at each fenced start decision, before preparation and the queued-to-running transition. A job that has not passed that decision remains queued with its input, delivery and attempt count unchanged; core queue suspension releases its item without deleting it. Re-enabling lets the same retained job start, subject to the existing job/state checks.

A configuration save is not atomic with a decision already made by another process. Work past the decision may still appear queued during preparation and may dispatch to the provider or finish after disabling. It drains under the existing cancellation checks, deadlines and workspace cleanup. Disabling does not instantly revoke a remote request, purge data or establish an immediate global shutdown. Use owner cancellation and let active workers finish within their configured execution bounds when stopping work already past the decision.

GET /healthz remains 200 for liveness. Disabled GET /readyz returns 503 not_ready; after re-enabling, the configured readiness checks apply. See health probes and review execution.

Worker and probes

Run the Composer-installed executable under the deployment's process supervisor:

vendor/bin/run-review-worker.php vendor/bin/drush 300 5

The three arguments are the host Drush executable, queue lease seconds and queue claim-window seconds. Review these example lease/window values against the actual deployment's execution policy. Web, worker and cron need the same storage account, keys, lock mount and site settings. Quiesce them together before changes to the locking protocol or mount. Keep normal Drupal cron running.

Health probes distinguish local readiness from a successful review. Validate an isolated synthetic review through submission, queue/worker, provider response and result retrieval before normal operation. A ready response does not establish that the provider network, worker or credentials work.