From c4be0649430eb4aa7ed00e8de0d3912ea6d333f0 Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 10:42:02 -0700 Subject: [PATCH 1/7] docs(readme): add /install-code-review setup and expand security review instructions Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 76 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index dd6141d..398b1fe 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,29 @@ Everything runs inside GitHub Actions using your Factory API key, so the bot nev ## Installation +### Quick Setup with `/install-code-review` (Recommended) + +The fastest way to get up and running is the guided installer built into the Droid CLI. From any local clone of your repo, run: + +```bash +droid +> /install-code-review +``` + +The guided flow will: + +- Detect whether your repository lives on GitHub or GitLab. +- Help you install the Droid GitHub App (or configure GitLab access). +- Generate the workflow files (`droid.yml` and `droid-review.yml`) with sensible defaults. +- Prompt you for `review_depth`, security review options, and other inputs. +- Open a PR/MR containing the new workflow files for you to review and merge. + +For GitHub-only setups you can also run `/install-github-app`. See the [Automated Code Review guide](https://docs.factory.ai/guides/droid-exec/code-review) and the [GitHub App installation guide](https://docs.factory.ai/cli/features/install-github-app) for full details. + +### Manual Setup + +If you prefer to wire things up by hand: + 1. **Install the Droid GitHub App** - Install from the Factory dashboard and grant it access to the repositories where you want Droid to operate. 2. **Create a Factory API Key** @@ -108,9 +131,10 @@ jobs: with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true + automatic_security_review: true ``` -Set `automatic_review: true` to run code reviews automatically on non-draft PRs. +Set `automatic_review: true` to run code reviews automatically on non-draft PRs. Set `automatic_security_review: true` to additionally run a STRIDE-based security review concurrently on every non-draft PR. ## Using the Commands @@ -128,16 +152,60 @@ Set `automatic_review: true` to run code reviews automatically on non-draft PRs. ### `@droid security` -- Mention `@droid security` in a PR comment. -- Droid performs a security-focused review using STRIDE methodology (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege). -- Findings include severity levels, CWE references, and suggested fixes. +- Mention `@droid security` in a PR comment to trigger an on-demand security review of the PR diff. +- Droid runs a security-focused review using STRIDE methodology (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege) along with OWASP Top 10 and OWASP LLM Top 10 checks. +- Each finding includes a severity level, CWE reference (where applicable), an explanation, and a suggested fix posted as inline review comments. +- Set `automatic_security_review: true` in your auto-review workflow to run the security pass on every non-draft PR alongside the standard code review (the two run concurrently). ### `@droid security --full` -- Performs a full repository security scan (not just PR changes). -- Creates a new branch with a security report at `.factory/security/reports/security-report-{date}.md`. -- Opens a PR with findings and auto-generated patches where possible. -- Useful for scheduled security audits. +- Performs a full repository security scan instead of just PR changes — useful for scheduled audits or onboarding a new repo. +- Creates a new branch and opens a PR containing a security report at `.factory/security/reports/security-report-{date}.md` plus auto-generated patches where Droid is confident in the fix. +- To run on a schedule, invoke the action from a cron-triggered workflow with `security_scan_schedule: true`. Use `security_scan_days` to control how many days of recent commits are included. + +#### Enabling automatic security review + +To run the security review on every non-draft PR (alongside the regular code review), add `automatic_security_review: true` to your `droid-review.yml`: + +```yaml +- name: Run Droid Auto Review + uses: Factory-AI/droid-action@v5 + with: + factory_api_key: ${{ secrets.FACTORY_API_KEY }} + automatic_review: true + automatic_security_review: true +``` + +#### Scheduling full-repo scans + +```yaml +name: Droid Security Scan + +on: + schedule: + - cron: "0 9 * * 1" # Every Monday at 09:00 UTC + workflow_dispatch: + +jobs: + security-scan: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + + - uses: Factory-AI/droid-action@v5 + with: + factory_api_key: ${{ secrets.FACTORY_API_KEY }} + security_scan_schedule: true + security_scan_days: 7 +``` ## Configuration From 0e0d9d52184b64d369245f1c9147f41009bc979f Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 10:57:38 -0700 Subject: [PATCH 2/7] docs(readme): pin workflow examples to @main instead of @v5 The /install-code-review installer generates workflows pinned to @main, so align the README examples for consistency. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 398b1fe..54a2473 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ jobs: fetch-depth: 1 - name: Run Droid Exec - uses: Factory-AI/droid-action@v5 + uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} ``` @@ -127,7 +127,7 @@ jobs: fetch-depth: 1 - name: Run Droid Auto Review - uses: Factory-AI/droid-action@v5 + uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true @@ -169,7 +169,7 @@ To run the security review on every non-draft PR (alongside the regular code rev ```yaml - name: Run Droid Auto Review - uses: Factory-AI/droid-action@v5 + uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true @@ -200,7 +200,7 @@ jobs: with: fetch-depth: 0 - - uses: Factory-AI/droid-action@v5 + - uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} security_scan_schedule: true @@ -239,20 +239,20 @@ The `review_depth` input controls which model and reasoning effort are used for ```yaml # Deep review (default - no extra config needed) -- uses: Factory-AI/droid-action@v5 +- uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true # Shallow review for faster feedback -- uses: Factory-AI/droid-action@v5 +- uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true review_depth: shallow # Fully custom model (overrides depth preset entirely) -- uses: Factory-AI/droid-action@v5 +- uses: Factory-AI/droid-action@main with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true From a22d92efc4131ac12e7be632ebe7e5bd6c898bb8 Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 11:36:43 -0700 Subject: [PATCH 3/7] docs(readme): drop internal 'Updating Review Models' section The section showed users the source-level REVIEW_DEPTH_PRESETS object and told them to edit src/utils/review-depth.ts -- but droid-action consumers can't change Factory-managed defaults from their workflow. The Review Depth table just above already shows the current shallow/deep defaults, and the YAML examples already show how to pin a specific model via review_model. Replace the section with a one-line note that the defaults are managed by Factory and may change, and that review_model is the way to pin a specific model in a workflow. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/README.md b/README.md index 54a2473..ec3fe67 100644 --- a/README.md +++ b/README.md @@ -262,23 +262,7 @@ The `review_depth` input controls which model and reasoning effort are used for > **Tip:** Setting `review_model` or `reasoning_effort` explicitly always takes priority over the depth preset. You can mix and match -- for example, use `review_depth: shallow` but override just `reasoning_effort: high` to get the shallow model with higher reasoning. -### Updating Review Models - -The depth presets are defined in [`src/utils/review-depth.ts`](src/utils/review-depth.ts). To change which models are used for shallow or deep reviews, edit the `REVIEW_DEPTH_PRESETS` object: - -```typescript -const SHALLOW_DEFAULTS = { - model: "kimi-k2-0711", // Change to any supported model - reasoningEffort: undefined, // undefined = use model default -}; - -const DEEP_DEFAULTS = { - model: "gpt-5.2", // Change to any supported model - reasoningEffort: "high", // "high" | "medium" | "low" | undefined -}; -``` - -Individual users can also override these defaults per-workflow without modifying the source by setting `review_model` and/or `reasoning_effort` inputs directly in their workflow YAML. +The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any supported model in your workflow (see the third example above). ### Security Configuration From a37f4aae859f50798cc8298276b41b605c5c1950 Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 11:40:29 -0700 Subject: [PATCH 4/7] docs(readme): clarify review_model accepts CLI model IDs (short or versioned) The third YAML example used 'claude-sonnet-4-5-20250929' without explaining that review_model takes any model identifier supported by 'droid exec --model'. Add a sentence pointing to the CLI reference's available-models list and noting that both short forms (claude-sonnet-4-6) and versioned forms (claude-sonnet-4-5-20250929) work, with the difference being whether the ID floats with the latest minor or pins to a specific release. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ec3fe67..d7482a7 100644 --- a/README.md +++ b/README.md @@ -262,7 +262,7 @@ The `review_depth` input controls which model and reasoning effort are used for > **Tip:** Setting `review_model` or `reasoning_effort` explicitly always takes priority over the depth preset. You can mix and match -- for example, use `review_depth: shallow` but override just `reasoning_effort: high` to get the shallow model with higher reasoning. -The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any supported model in your workflow (see the third example above). +The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any model identifier supported by `droid exec --model` -- the [CLI reference](https://docs.factory.ai/reference/cli-reference#available-models) has the canonical list. Both short forms (`claude-sonnet-4-6`, `gpt-5.5`, `kimi-k2.6`) and fully-versioned forms (`claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`) are valid -- versioned IDs pin to a specific release, short forms float with the latest minor. ### Security Configuration From 915e66120f0822bb5e1cc51f9343a8883723875b Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 11:45:47 -0700 Subject: [PATCH 5/7] docs(readme): use short model-ID forms in review_model example Replace the versioned 'claude-sonnet-4-5-20250929' example with the short 'claude-sonnet-4-6' and drop the explainer about versioned IDs. Short forms are the recommended path -- they float with the latest minor and are easier to remember; versioned IDs are still valid but unnecessary noise here. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d7482a7..dab133f 100644 --- a/README.md +++ b/README.md @@ -256,13 +256,13 @@ The `review_depth` input controls which model and reasoning effort are used for with: factory_api_key: ${{ secrets.FACTORY_API_KEY }} automatic_review: true - review_model: claude-sonnet-4-5-20250929 + review_model: claude-sonnet-4-6 reasoning_effort: high ``` > **Tip:** Setting `review_model` or `reasoning_effort` explicitly always takes priority over the depth preset. You can mix and match -- for example, use `review_depth: shallow` but override just `reasoning_effort: high` to get the shallow model with higher reasoning. -The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any model identifier supported by `droid exec --model` -- the [CLI reference](https://docs.factory.ai/reference/cli-reference#available-models) has the canonical list. Both short forms (`claude-sonnet-4-6`, `gpt-5.5`, `kimi-k2.6`) and fully-versioned forms (`claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`) are valid -- versioned IDs pin to a specific release, short forms float with the latest minor. +The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any model ID supported by `droid exec --model` (e.g. `claude-sonnet-4-6`, `gpt-5.5`, `kimi-k2.6`) -- the [CLI reference](https://docs.factory.ai/reference/cli-reference#available-models) has the full list. ### Security Configuration From 70c4d51781a934d14b6f13da63fc3c3db34c6d9b Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 11:47:07 -0700 Subject: [PATCH 6/7] docs(readme): add sample model table for review_model Replace the inline three-example list with a small table of common model IDs (Anthropic Opus/Sonnet/Haiku, OpenAI GPT-5.5/5.5-pro/5.3-codex, Kimi K2.6) each with a one-line note on when to pick it. Easier for users to skim than a sentence with parenthetical examples. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dab133f..8defea4 100644 --- a/README.md +++ b/README.md @@ -262,7 +262,19 @@ The `review_depth` input controls which model and reasoning effort are used for > **Tip:** Setting `review_model` or `reasoning_effort` explicitly always takes priority over the depth preset. You can mix and match -- for example, use `review_depth: shallow` but override just `reasoning_effort: high` to get the shallow model with higher reasoning. -The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any model ID supported by `droid exec --model` (e.g. `claude-sonnet-4-6`, `gpt-5.5`, `kimi-k2.6`) -- the [CLI reference](https://docs.factory.ai/reference/cli-reference#available-models) has the full list. +The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any model ID supported by `droid exec --model`. A few common choices: + +| Model ID | Notes | +| --------------------- | -------------------------------------------------------------- | +| `claude-opus-4-7` | Claude Opus 4.7 — strongest reasoning, highest cost | +| `claude-sonnet-4-6` | Claude Sonnet 4.6 — balanced quality and cost | +| `claude-haiku-4-5` | Claude Haiku 4.5 — fastest Anthropic option | +| `gpt-5.5` | GPT-5.5 — strong general-purpose reasoning | +| `gpt-5.5-pro` | GPT-5.5 Pro — deeper reasoning, slower | +| `gpt-5.3-codex` | GPT-5.3 Codex — code-tuned variant | +| `kimi-k2.6` | Droid Core (Kimi K2.6) — fast and cost-effective | + +See the [CLI reference](https://docs.factory.ai/reference/cli-reference#available-models) for the canonical, up-to-date list. ### Security Configuration From 7bf5107e188976bc866083fa383b2f68aa72dbf8 Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Tue, 28 Apr 2026 11:48:27 -0700 Subject: [PATCH 7/7] docs(readme): drop notes column from review_model sample list Just list the model IDs without descriptions -- the CLI reference is the canonical source for what each model is. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8defea4..7e19b78 100644 --- a/README.md +++ b/README.md @@ -264,15 +264,13 @@ The `review_depth` input controls which model and reasoning effort are used for The default models (`gpt-5.2` for `deep`, `kimi-k2-0711` for `shallow`) are managed by Factory and may change over time. To pin a specific model regardless of the depth preset, set `review_model` to any model ID supported by `droid exec --model`. A few common choices: -| Model ID | Notes | -| --------------------- | -------------------------------------------------------------- | -| `claude-opus-4-7` | Claude Opus 4.7 — strongest reasoning, highest cost | -| `claude-sonnet-4-6` | Claude Sonnet 4.6 — balanced quality and cost | -| `claude-haiku-4-5` | Claude Haiku 4.5 — fastest Anthropic option | -| `gpt-5.5` | GPT-5.5 — strong general-purpose reasoning | -| `gpt-5.5-pro` | GPT-5.5 Pro — deeper reasoning, slower | -| `gpt-5.3-codex` | GPT-5.3 Codex — code-tuned variant | -| `kimi-k2.6` | Droid Core (Kimi K2.6) — fast and cost-effective | +- `claude-opus-4-7` +- `claude-sonnet-4-6` +- `claude-haiku-4-5` +- `gpt-5.5` +- `gpt-5.5-pro` +- `gpt-5.3-codex` +- `kimi-k2.6` See the [CLI reference](https://docs.factory.ai/reference/cli-reference#available-models) for the canonical, up-to-date list.