Skip to content
Agentic Suite

Register and install the GitHub App

The GitHub App lets the Security Reviewer read your repositories and pull requests and post its verdict back. You register the App once on GitHub, upload the Agentic Suite icon there, then set a few environment variables on the backend.

1. Register the App

Open github.com/settings/apps/new and set the following.

  • GitHub App name: Agentic Suite Security (the bot becomes agentic-suite-security[bot]).
  • Homepage URL: your product or repository URL.
  • Webhook: set Active on, and set the Webhook URL to https://api.agenticsuite.app/api/v1/security/github/webhook.
  • Webhook secret: generate a strong random string and keep it. You will set it as GITHUB_APP_WEBHOOK_SECRET.

Repository permissions (least privilege)

The reviewer only reads code. It needs write only to post its verdict comment and label on a pull request.

  • Contents: Read-only
  • Pull requests: Read and write (to post the verdict comment and label)
  • Metadata: Read-only (required by GitHub)

Subscribe to events

  • Pull request

Set Where can this app be installed? to match your plan. Choose Only on this account if it is just for you, or Any account if you offer it to others.

2. Add the Agentic Suite icon

On the App settings page, upload the Agentic Suite logo as the App icon and pick a background color. This is what people see on the install screen and on the [bot] badge.

3. Generate credentials

On the App settings page:

  • Note the App ID.
  • Note the App slug (the name in the App URL, for example agentic-suite-security).
  • Generate a private key. A .pem file downloads. Store it somewhere private on the backend host, for example /etc/agentic-suite/github-app.pem with tight permissions.

4. Install it on your repositories

From the App page choose Install App, pick the repositories to review, and finish. After installing, the URL ends in /installations/<INSTALLATION_ID>.

5. Wire the backend

Set these environment variables on the backend and workers, then restart them.

Terminal window
export GITHUB_APP_ID=<app-id>
export GITHUB_APP_SLUG=agentic-suite-security
export GITHUB_APP_PRIVATE_KEY_PATH=/etc/agentic-suite/github-app.pem
export GITHUB_APP_WEBHOOK_SECRET=<the-secret-you-generated>

You can pass the key inline with GITHUB_APP_PRIVATE_KEY instead of a path if that suits your deployment.

There are two ways to tell Agentic Suite which organization owns an installation.

In the app, open Security Reviews and click Connect GitHub. After you install the App on GitHub, the app links that installation to your organization. From then on, pull requests on the installed repositories are reviewed automatically. You can review your linked installations in the same place.

Config allowlist (self-hosted)

Alternatively, map repositories to an organization in ~/.agentic_suite/security-review.json. The webhook resolves the organization from a linked installation first, then falls back to this allowlist. Either way, only repositories mapped to an organization are reviewed, so a stray install cannot consume another organization’s quota.

{
  "enabled": true,
  "dry_run": true,
  "repos": [
    {
      "kind": "github_pr",
      "repo": "your-org/your-repo",
      "organization_id": "YOUR_ORG_UUID"
    }
  ]
}

Leave dry_run set to true while you test. The reviewer will store reports without posting to the pull request. When you are ready for it to post the verdict back, set dry_run to false. See Safety controls.

7. Verify

Open a pull request on an allowlisted repository. Within a moment a review is queued, and the report appears in the review history. With dry_run off, the verdict is also posted as a comment and a label on the pull request. See Auto-review on pull requests.