Skip to content

deployment.md

Latest commit

 

History

History
179 lines (133 loc) · 8.35 KB

deployment.md

File metadata and controls

179 lines (133 loc) · 8.35 KB
Raw

Deploy Guard

This guide puts Guard on a production site and connects it to GitHub with a GitHub App. GitHub sends webhooks to the site, and Guard posts reviews as the App.

Before you start

You need:

  • A Frappe v16 site that GitHub can reach on a public HTTPS URL. In this guide, the URL is https://guard.example.com.
  • The URL and key of at least one AI provider. Guard uses Grove, OpenRouter, Anthropic, OpenAI, or any other OpenAI-compatible or Anthropic-compatible endpoint. It can use several at the same time.
  • Owner access to the GitHub organization or account that will own the App.

The server must have:

Requirement Why
Python 3.14 or later Guard requires it.
The git command Guard keeps a mirror of each repository.
Persistent disk The mirrors are in sites/<site>/private/guard/git/.
Workers for the short, default and long queues Webhooks run on short, reviews on default, and indexing on long. Refer to Size the workers.
The scheduler Guard polls reactions and runs maintenance jobs.
MariaDB 11.7 or later (recommended) Native vector search. Older versions use a slower fallback.
podman (optional) Only for runtime validation, which runs tests in a container.

1. Install the app

bench get-app https://github.com/<owner>/guard --branch develop
bench --site guard.example.com install-app guard

On a hosted platform, add the app to the bench and install it on the site from the dashboard.

2. Connect the AI providers

  1. In Desk, open AI Provider and add one record for each AI provider. Set Name, Base URL and API Key, and set Dialect to anthropic for an Anthropic-compatible API. Do not add /v1 to the URL. Guard adds it. Examples:
    • Grove: the URL of your gateway, dialect openai.
    • OpenRouter: https://openrouter.ai/api, dialect openai.
    • Anthropic: https://api.anthropic.com, dialect anthropic.
  2. Click Fetch models on each AI provider to test it.
  3. Open Guard Settings. Set Default AI Provider.
  4. Click Fetch models.
  5. Set Base Model, Plus Model, Apex Model and Fast Model. To run a model on an AI provider other than the default, set the AI provider field next to it, for example Apex AI Provider.
  6. Set Embedding Model if an AI provider has one, and Embedding AI Provider if that is not the default. If none has one, leave it empty. Guard then uses a simpler local fallback for search.
  7. Set Public URL to https://guard.example.com. Links in review comments use this URL.
  8. Save.

To review with no model cost, turn on Offline Mode in Guard Settings. Guard then calls no AI provider. Reviews post only the checks that need no model: secrets, calls to other repositories, project test rules and, for a Frappe app, the Frappe checks. Guard does not answer questions in threads. A change of the mode rebuilds the search vectors of every repository.

When an AI provider stays down, reviews wait for it. After Review Without AI After (Seconds) (default 900), a waiting review posts the checks that need no model, and a full review of the same commit follows when the AI provider answers. Set it to 0 to keep reviews waiting.

3. Create the GitHub App

  1. Open the settings of the organization or account that will own the App. Go to Developer settings, then GitHub Apps, then New GitHub App.

  2. Set a name, for example acme-guard, and a homepage URL.

  3. Make a webhook secret:

    openssl rand -hex 24

  4. Under Webhook, select Active and set:

    • Webhook URL: https://guard.example.com/api/method/guard.webhooks.endpoint.github_webhook?provider=GitHub
    • Secret: the value from step 3.

  5. Set the repository permissions:

    Permission Access
    Checks Read and write
    Commit statuses Read and write
    Contents Read and write
    Issues Read and write
    Pull requests Read and write
    Metadata Read

    Guard does not push code. GitHub requires Contents write access to resolve review threads.

  6. Set the organization permission Members to Read.

  7. Subscribe to these events:

    • Check run
    • Issue comment
    • Pull request
    • Pull request review
    • Pull request review comment
    • Pull request review thread
    • Push

  8. Under Where can this GitHub App be installed?, select Only on this account.

  9. Click Create GitHub App.

  10. Record the App ID and the slug. The slug is the last part of the App URL.

  11. Click Generate a private key. GitHub downloads a .pem file.

4. Add the Code Provider

  1. In Desk, create a Code Provider.

  2. Set these fields:

    Field Value
    Title GitHub
    Provider Type GitHub
    Auth Mode App
    App ID The App ID from step 3
    App Slug The slug from step 3
    Private Key The full contents of the .pem file
    Webhook Secret The secret from step 3

  3. Save.

  4. Click Test connection. The result must be "Connected as" and the App slug.

  5. Delete the .pem file from your computer. Guard keeps the key encrypted.

The title must be GitHub, because the webhook URL uses provider=GitHub. If you use a different title, change the webhook URL to match.

5. Install the App on repositories

  1. Open https://github.com/apps/<slug>/installations/new.
  2. Select the account, then the repositories.
  3. Click Install.

GitHub sends an installation webhook. Guard then:

  • creates a Guard Team for the account;
  • creates a Code Repository for each repository;
  • enables reviews and starts indexing, when Auto Enable New Repositories is on.

To add repositories later, change the installation on GitHub. Guard receives the change.

6. Check the setup

  1. In Desk, open Webhook Delivery. The installation delivery must have the status Processed.
  2. Open Code Repository. Each repository must show the index status Indexed after some minutes.
  3. Open a test pull request.
  4. Make sure that Guard:
    • adds an 👀 reaction;
    • posts a summary comment with a confidence score;
    • sets a check named Guard.

If a delivery has the status Failed, open it to see the error. If no delivery arrives, open the App on GitHub, go to Advanced, and look at Recent Deliveries.

Size the workers

Give each queue its own workers. Then a long job on one queue does not stop the others.

Queue Jobs Workers
short Webhooks, and small jobs after a review 3
default Reviews (base and plus tier), replies to comments 4 to 6
long Indexing, knowledge base builds, apex reviews 2

Do not add a worker for all three queues together.

Each worker is a full Frappe process. It uses about 130 MB of memory when it is idle, and up to 500 MB when it indexes a large repository such as erpnext. Calculate the memory for the workers as the number of workers × 500 MB, and add memory for MariaDB, Redis and the web workers.

Server Workers
2 vCPU, 8 GB 3 short, 4 default, 2 long
4 vCPU, 16 GB 3 short, 6 default, 2 long

More workers do not make reviews faster when the server is full. If the server uses 100% CPU, look at the memory first. Too many workers fill the memory, and then the server swaps.

Default behavior

Setting Default
Reviews On pull request open and on each push
Re-reviews Post P2 findings only on lines added since the last review
Earlier findings Guard resolves a thread when the code fixes the finding, or when the finding no longer applies
Guard check Passes only at 5/5 with no open findings
Approval Guard approves at 5/5 with no open findings. A new push dismisses the approval.
Summary sections Collapsed

To change these settings, open Review Settings in Desk, or add .guard/config.toml to a repository. Refer to Configure Guard.

To stop Guard from approving pull requests, clear Auto Approve in Review Settings.

Rotate secrets

  • Webhook secret: make a new value. Set it on the GitHub App and in the Code Provider at the same time.
  • Private key: generate a new key on the GitHub App. Paste it into the Code Provider. Then delete the old key on GitHub.
  • AI provider key: set the new key in the AI Provider. Then revoke the old key at the provider.