Policy Engine defines the default review policy for the workspace. It controls which review types are active, which additional instructions should guide analysis, and which authors should be included or blocked.
Use Console > Policy Engine to configure the workspace default. Use repository settings only for exceptions.
Who can access
Policy Engine requires a Workspace admin (platform admins also have access). Roles are fixed capability sets defined by Acrity, so this access is not configurable per organization.
When to use
Use this screen to:
- enable or disable review tiers in the workspace;
- add general review instructions;
- define bots that can be reviewed;
- block authors that should not generate reviews;
- view or rotate webhook settings when the screen displays that option;
- align the default policy before connecting many repositories.
Review tiers
| Tier | Typical use |
|---|
Fast | More direct review for common changes, focused on quick feedback. |
Deep | More complete review for changes that require more careful analysis. |
Do not use tiers as a substitute for branch rules. Branch rules should stay in Console > Repositories.
Additional instructions
Additional instructions let you adapt review to the organization’s standards.
Use them to record guidance such as:
- expected architecture patterns;
- quality criteria relevant to the organization;
- care around testing, security, or compatibility;
- expected language in comments;
- product decisions that should be considered.
Avoid including:
- secrets;
- tokens;
- confidential customer information;
- internal rules that should not appear in review outputs;
- instructions that are too specific to a single repository.
For repository-specific rules, use Console > Repositories > Detail > Review.
Reviewer prompt overrides
Each reviewer role has its own prompt-override field, so you can fine-tune how a specific reviewer analyzes changes across the workspace.
| Reviewer | Guides |
|---|
| Architect | Structure, design, and how a change fits the broader system. |
| Spec Validator | Alignment between the change and its stated requirements. |
| QA Engineer | Test coverage, edge cases, and overall quality. |
- accepts up to 2,000 characters;
- shows whether the current text is a workspace override or the global default;
- provides a Revert to global action that discards the workspace override and restores the global default.
When a field shows the global default, that reviewer uses Acrity’s built-in guidance. When you save text into a field, it becomes a workspace override that applies to reviews across the workspace, replacing the global default for that reviewer.
Use reviewer prompt overrides with caution. They change reviewer behavior across the whole workspace, and it is easy to forget an override is in place. For durable, long-lived guidance, prefer committing an ARCHITECTURE.md file to the repository so the guidance lives with the code and is versioned alongside it.
Author policy
Author policy helps control which changes should be reviewed.
| Field | Purpose |
|---|
| Allowed bots | Identifies automated accounts whose PRs/MRs can be reviewed. |
| Blocked authors | Prevents reviews for specific authors. |
Webhook key or URL
Some workspaces can display webhook configuration linked to the review flow.
When the screen displays this option:
- copy the URL only to the correct provider;
- treat the key as a secret;
- rotate the key if exposure is suspected;
- update the provider after rotation;
- validate the webhook through the Console or provider.
Do not share webhook keys in chats, public tickets, PR/MR comments, or broad internal documentation.
Open Policy Engine
Go to Console > Policy Engine.
Review tiers
Enable Fast, Deep, or both according to the workspace policy.
Add instructions
Fill in general additional instructions that apply to most repositories.
Adjust reviewer prompts (optional)
Set a workspace override for the Architect, Spec Validator, or QA Engineer reviewer only when needed, and revert to the global default when it is no longer required.
Configure authors
Add allowed bots and blocked authors when needed.
Save
Save and confirm validation messages.
Test in a repository
Choose a representative repository and track the next review in the Ops dashboard to validate the expected behavior.
Relationship with repository settings
| Level | Best use |
|---|
| Workspace | Default policy for most repositories. |
| Repository | Exceptions for projects with specific needs. |
Best practices
- Write short, clear, verifiable instructions.
- Avoid duplicating long documentation inside the instructions field.
- Do not include secrets or confidential data.
- Review the policy after major process changes.
- Use repository-level exceptions sparingly.
- Revert reviewer prompt overrides to the global default once they are no longer needed, and keep durable guidance in the repository
ARCHITECTURE.md.
- Combine author policy with branch rules to reduce noise.
Common issues
| Symptom | What to check |
|---|
| I cannot save | Confirm that at least one tier is active and that fields pass screen validation. |
| A repository does not follow the default | Check whether it has its own setting in the Review tab. |
| Reviews are noisy | Review additional instructions, author policy, and repository branch rules. |
| A reviewer behaves unexpectedly everywhere | Check whether a workspace prompt override is set for that reviewer and use Revert to global if needed. |
| Expected bot was not reviewed | Confirm that the account is in allowed bots and that the event matches repository rules. |
| Author still generates reviews | Check spelling, provider identifier, and repository configuration. |
