Discussion: org-wide or instance-wide auto_review provisioning #145

New issue

Closed

opened 2026-05-07 14:55:27 -07:00 by jwilger · 0 comments

jwilger commented

2026-05-07 14:55:27 -07:00

Owner

Discussion placeholder

This is not an implementation ticket and should not be picked up as a scoped feat(...) task yet. It exists to capture design notes and trade-offs around whether auto_review could support org-wide or instance-wide Forgejo provisioning.

Context

Question raised: when both Forgejo and auto_review are deployed via NixOS / the auto_review flake, could auto_review automatically configure itself for all repos on the system instead of requiring one repo at a time?

The desired behavior would be:

Configure bot access, webhooks, Actions secrets, and related membership broadly.
Reviews would still not run by default.
A repo would only trigger semantic review if its CI explicitly calls the gateway's /reviews/ci endpoint.

Initial design notes

Pure flake evaluation should not mutate Forgejo or contain live secrets. If this exists, it should likely be a runtime provisioning/reconciliation path, for example:

a NixOS module option that enables an idempotent systemd oneshot/timer;
a standalone operator CLI command;
or both, with the NixOS module wrapping the CLI.

The cleanest model appears to be org-level provisioning:

Create or reference the auto-review bot user.
Ensure the bot belongs to an org team with access to all intended repos.
Install an org-level webhook for pull_request events, and possibly issue_comment if chat commands are desired.
Install an org-level Actions secret such as AUTO_REVIEW_ACTION_TOKEN.
Let individual repos opt in by adding a CI job that calls the gateway.

Instance-wide provisioning may be possible with Forgejo system hooks or API reconciliation, but personal/user-owned repos probably need explicit enumeration, policy, or periodic reconciliation.

Security / operational caveats

Provisioning should use a separate admin/provisioner credential, not the gateway bot PAT.
The provisioner credential should not be present in the gateway environment.
Generated/shared secrets should stay out of the Nix store, e.g. via sops-nix, agenix, or root-owned runtime files.
Broad bot access increases blast radius for AR_FORGEJO_TOKEN, AR_CI_REVIEW_TOKEN, webhook secret drift, and accidental workflow use.
If issue_comment is installed globally, @auto_review re-review can intentionally bypass CI gating. A CI-only deployment may want to omit comment events or add a future chat-command allowlist/config switch.

Possible future shape

A future operator interface might look conceptually like:

auto-review forgejo provision \
  --org engineering \
  --gateway-url https://reviewer.example.com \
  --ensure-webhook \
  --ensure-actions-secret \
  --ensure-bot-access

Or via NixOS:

services.auto-review.forgejoProvisioning = {
  enable = true;
  forgejoBaseUrl = "https://git.example.com";
  gatewayUrl = "https://reviewer.example.com";
  botUser = "auto-review";
  organizations = [ "engineering" "infra" ];
  adminTokenFile = config.sops.secrets.forgejo-provisioner-token.path;
  webhookSecretFile = config.sops.secrets.auto-review-webhook.path;
  ciTokenFile = config.sops.secrets.auto-review-ci-token.path;
};

Open discussion questions

Should this target org-wide provisioning first and defer true instance-wide support?
Should chat command hooks be separately configurable from PR intake hooks?
Should the CLI reconcile existing hooks/secrets idempotently rather than only creating new ones?
What Forgejo API support exists across versions for org/system webhooks and org-level Actions secrets?
What threat-model updates would be needed if broad provisioning becomes supported?

Again, this issue is only a placeholder for discussion and design capture, not a request to implement the feature as currently described.

## Discussion placeholder This is **not** an implementation ticket and should not be picked up as a scoped `feat(...)` task yet. It exists to capture design notes and trade-offs around whether `auto_review` could support org-wide or instance-wide Forgejo provisioning. ## Context Question raised: when both Forgejo and `auto_review` are deployed via NixOS / the `auto_review` flake, could `auto_review` automatically configure itself for all repos on the system instead of requiring one repo at a time? The desired behavior would be: - Configure bot access, webhooks, Actions secrets, and related membership broadly. - Reviews would still **not** run by default. - A repo would only trigger semantic review if its CI explicitly calls the gateway's `/reviews/ci` endpoint. ## Initial design notes Pure flake evaluation should not mutate Forgejo or contain live secrets. If this exists, it should likely be a runtime provisioning/reconciliation path, for example: - a NixOS module option that enables an idempotent `systemd` oneshot/timer; - a standalone operator CLI command; - or both, with the NixOS module wrapping the CLI. The cleanest model appears to be org-level provisioning: 1. Create or reference the `auto-review` bot user. 2. Ensure the bot belongs to an org team with access to all intended repos. 3. Install an org-level webhook for `pull_request` events, and possibly `issue_comment` if chat commands are desired. 4. Install an org-level Actions secret such as `AUTO_REVIEW_ACTION_TOKEN`. 5. Let individual repos opt in by adding a CI job that calls the gateway. Instance-wide provisioning may be possible with Forgejo system hooks or API reconciliation, but personal/user-owned repos probably need explicit enumeration, policy, or periodic reconciliation. ## Security / operational caveats - Provisioning should use a separate admin/provisioner credential, not the gateway bot PAT. - The provisioner credential should not be present in the gateway environment. - Generated/shared secrets should stay out of the Nix store, e.g. via `sops-nix`, `agenix`, or root-owned runtime files. - Broad bot access increases blast radius for `AR_FORGEJO_TOKEN`, `AR_CI_REVIEW_TOKEN`, webhook secret drift, and accidental workflow use. - If `issue_comment` is installed globally, `@auto_review re-review` can intentionally bypass CI gating. A CI-only deployment may want to omit comment events or add a future chat-command allowlist/config switch. ## Possible future shape A future operator interface might look conceptually like: ```sh auto-review forgejo provision \ --org engineering \ --gateway-url https://reviewer.example.com \ --ensure-webhook \ --ensure-actions-secret \ --ensure-bot-access ``` Or via NixOS: ```nix services.auto-review.forgejoProvisioning = { enable = true; forgejoBaseUrl = "https://git.example.com"; gatewayUrl = "https://reviewer.example.com"; botUser = "auto-review"; organizations = [ "engineering" "infra" ]; adminTokenFile = config.sops.secrets.forgejo-provisioner-token.path; webhookSecretFile = config.sops.secrets.auto-review-webhook.path; ciTokenFile = config.sops.secrets.auto-review-ci-token.path; }; ``` ## Open discussion questions - Should this target org-wide provisioning first and defer true instance-wide support? - Should chat command hooks be separately configurable from PR intake hooks? - Should the CLI reconcile existing hooks/secrets idempotently rather than only creating new ones? - What Forgejo API support exists across versions for org/system webhooks and org-level Actions secrets? - What threat-model updates would be needed if broad provisioning becomes supported? Again, this issue is only a placeholder for discussion and design capture, not a request to implement the feature as currently described.

jwilger added this to the (deleted) project

2026-05-10 07:35:54 -07:00

jwilger added the

discussion

label

2026-05-10 07:43:51 -07:00

jwilger added this to the 1.1 milestone

2026-05-10 07:44:51 -07:00

jwilger closed this issue

2026-05-19 21:19:01 -07:00