Skip to content

Commit f1252df

Browse files
factory-nizarfactory-droid[bot]
factory-nizar
and
factory-droid[bot]
committed
docs(gitlab): hide internal inputs, trim setup.md, default ref to main
Customer-facing surface cleanup before GA: * gitlab/templates/review.yml: change droid_action_ref default from "dev" to "main" so customers who don't set it track stable. Description annotated 'Internal: most users leave at the default'. * docs/gitlab-setup.md: drop droid_action_ref, droid_action_repo, stage from the Inputs table — they're for self-hosted GitLab mirrors / advanced overrides, not standard customer config. * docs/gitlab-setup.md: drop everything from 'How it works' onward (How it works, What's not yet supported, Troubleshooting, Self-hosted GitLab). Those belong in deeper docs / runbooks; the setup page should be exactly setup. * docs/gitlab-setup.md: drop the 'pin to a release tag (e.g. v1)' advice — droid-action doesn't tag yet, and the @main URL pin is the canonical pattern. * gitlab/examples/.gitlab-ci.example.yml: drop droid_action_ref from the inputs block + drop the same line from the optional fill snippet. Update the comment to just explain the @main pin. * gitlab/examples/README.md: drop the 'custom stage' reference now that stage isn't documented as a user-facing knob. The hidden inputs still exist in the template with sensible defaults, so air-gapped customers mirroring droid-action can still override droid_action_repo or pin droid_action_ref to a private SHA — they just aren't part of the documented surface. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
1 parent ecd3fbe commit f1252df

4 files changed

Lines changed: 19 additions & 110 deletions

File tree

‎docs/gitlab-setup.md‎

Lines changed: 13 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -49,18 +49,15 @@ include:
4949
include_suggestions: "true"
5050
security_block_on_critical: "true"
5151
security_block_on_high: "false"
52-
droid_action_ref: "main"
5352

5453
droid-review:
5554
variables:
5655
FACTORY_API_KEY: $FACTORY_API_KEY
5756
GITLAB_TOKEN: $GITLAB_TOKEN
5857
```
5958
60-
> Pin both the `include:` URL ref and `droid_action_ref` to a release tag
61-
> (e.g. `v1`) once one is published. They MUST match — the URL pin
62-
> resolves the template at parse time, `droid_action_ref` clones the same
63-
> source at runtime.
59+
> The `include:` URL is pinned to `@main`, which tracks the latest stable
60+
> cut of droid-action.
6461

6562
### 3. Push an MR
6663

@@ -69,20 +66,17 @@ the `droid-review` job. Expect ~5-10 minutes for a typical change.
6966

7067
## Inputs
7168

72-
| Input | Default | Description |
73-
| ---------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
74-
| `automatic_review` | `"true"` | Run code review automatically on every MR pipeline. |
75-
| `automatic_security_review` | `"false"` | Run a parallel security-focused subagent on every MR pipeline. Findings are prefixed `[security]` and posted alongside code-review comments. |
76-
| `review_depth` | `"deep"` | `"deep"` (thorough) or `"shallow"` (fast). |
77-
| `review_model` | `""` | Override the model. Empty = use depth preset. |
78-
| `reasoning_effort` | `""` | Override reasoning effort. Empty = use depth preset. |
79-
| `include_suggestions` | `"true"` | Include code suggestion blocks in review comments when the fix is high-confidence. |
80-
| `security_block_on_critical` | `"true"` | Block merge on CRITICAL security findings. (Mirrors GitHub action; surface-level parity.) |
81-
| `security_block_on_high` | `"false"` | Block merge on HIGH security findings. (Mirrors GitHub action; surface-level parity.) |
82-
| `settings` | `""` | Droid Exec settings as a JSON string or a path to a JSON file. Merged into `~/.factory/droid/settings.json` before each `droid exec` call. |
83-
| `droid_action_repo` | `https://github.com/Factory-AI/droid-action.git` | Override if you mirror droid-action privately. |
84-
| `droid_action_ref` | `"dev"` | Git ref of droid-action to clone at runtime. Should match the `include: remote:` URL ref. |
85-
| `stage` | `"test"` | GitLab CI stage to assign the `droid-review` job to. |
69+
| Input | Default | Description |
70+
| ---------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
71+
| `automatic_review` | `"true"` | Run code review automatically on every MR pipeline. |
72+
| `automatic_security_review` | `"false"` | Run a parallel security-focused subagent on every MR pipeline. Findings are prefixed `[security]` and posted alongside code-review comments. |
73+
| `review_depth` | `"deep"` | `"deep"` (thorough) or `"shallow"` (fast). |
74+
| `review_model` | `""` | Override the model. Empty = use depth preset. |
75+
| `reasoning_effort` | `""` | Override reasoning effort. Empty = use depth preset. |
76+
| `include_suggestions` | `"true"` | Include code suggestion blocks in review comments when the fix is high-confidence. |
77+
| `security_block_on_critical` | `"true"` | Block merge on CRITICAL security findings. (Mirrors GitHub action; surface-level parity.) |
78+
| `security_block_on_high` | `"false"` | Block merge on HIGH security findings. (Mirrors GitHub action; surface-level parity.) |
79+
| `settings` | `""` | Droid Exec settings as a JSON string or a path to a JSON file. Merged into `~/.factory/droid/settings.json` before each `droid exec` call. |
8680

8781
## What you get
8882

@@ -99,57 +93,3 @@ Each MR pipeline produces:
9993
- **A custom droid library** copied from
10094
`$DROID_ACTION_DIR/.factory/droids` into `~/.factory/droids` on the
10195
runner, so subagents like `security-reviewer` are reachable.
102-
103-
## How it works
104-
105-
The pipeline runs in two passes:
106-
107-
1. **Pass 1 (candidates)** — Droid Exec reads the MR diff, description, and
108-
existing comments, then writes `/tmp/droid-prompts/review_candidates.json`
109-
with candidate findings. The security-reviewer subagent runs in parallel
110-
if `automatic_security_review` is on. **No MR mutations** happen in this
111-
pass — the MR-write tools are excluded from `--enabled-tools`.
112-
2. **Pass 2 (validator)** — Droid Exec rereads the candidates, filters out
113-
duplicates and low-confidence findings, and batches all approved comments
114-
into a single `gitlab_mr___submit_review` call. The sticky note is
115-
updated via `gitlab_mr___update_tracking_note`.
116-
117-
A small GitLab MCP server (`src/mcp/gitlab-mr-server.ts`) is launched on
118-
the runner to expose those two write tools.
119-
120-
## What's not yet supported
121-
122-
These exist in the GitHub action but require platform features GitLab
123-
does not currently expose, and are not part of Phase 1:
124-
125-
- **Comment-triggered modes** (`@droid review`, `@droid security`,
126-
`@droid fill`). GitLab does not fire CI pipelines on note events.
127-
Requires a Factory-hosted webhook receiver that turns note webhooks
128-
into `POST /projects/:id/trigger/pipeline` calls. Planned as a follow-up.
129-
- **`@droid fill` (MR description fill).** Depends on the comment trigger
130-
above.
131-
- **Scheduled full-repo security scans.** Tracked separately.
132-
133-
## Troubleshooting
134-
135-
| Symptom | Likely cause | Fix |
136-
| --------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
137-
| Pipeline runs but no comments posted | `GITLAB_TOKEN` not set or missing `api` scope | Add a masked `GITLAB_TOKEN` CI/CD variable with `api`-scoped PAT |
138-
| `Could not find file` on include | `droid_action_ref` doesn't exist in `Factory-AI/droid-action` | Verify the ref; pin to a stable tag |
139-
| `factory_api_key is required` error | `FACTORY_API_KEY` not set or scoped wrong | Add as **masked**, **unprotected** variable at the right level (project / subgroup / top-level group) |
140-
| Sticky note posts but inline findings missing | Pass 2 hit a transient API error | Inspect `.droid-debug/prompts/pass2-output.jsonl`; re-run the pipeline |
141-
| Pipeline times out | Very large MR | Set `review_depth: "shallow"` for faster feedback |
142-
143-
## Self-hosted GitLab
144-
145-
The component reads `CI_API_V4_URL` and `CI_SERVER_URL` from the standard
146-
GitLab CI environment. Self-managed GitLab works as long as your runner
147-
can:
148-
149-
- Reach `https://app.factory.ai/cli` to install the Droid CLI
150-
- Reach `https://github.com/Factory-AI/droid-action.git` (or your private
151-
mirror, via `droid_action_repo`)
152-
- Reach `https://raw.githubusercontent.com/...` for the `include: remote:`
153-
154-
Mirror droid-action internally and set `droid_action_repo` + `droid_action_ref`
155-
accordingly if your runners cannot reach GitHub.

‎gitlab/examples/.gitlab-ci.example.yml‎

Lines changed: 3 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -19,52 +19,21 @@
1919
# group level, depending on how widely you want the review to roll out.
2020

2121
include:
22-
# Pin to a release tag once droid-action publishes one. Until then,
23-
# `main` tracks the latest stable cut. `droid_action_ref` below MUST
24-
# match the ref in this URL so the template and the runtime source
25-
# stay consistent.
22+
# The URL is pinned to @main, which tracks the latest stable cut of
23+
# droid-action.
2624
- remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/review.yml"
2725
inputs:
2826
# ---- core review behavior ----
2927
automatic_review: "true" # run on every MR event; "false" disables
30-
review_depth: "deep" # "deep" (gpt-5.2 / high) or "shallow" (kimi-k2.6 / none)
28+
review_depth: "deep" # "deep" (thorough) or "shallow" (fast)
3129
include_suggestions: "true" # post code-suggestion blocks for high-confidence fixes
3230

3331
# ---- security review (parallel security-reviewer subagent) ----
3432
automatic_security_review: "false" # enable to flag vulns alongside the regular review
3533
security_block_on_critical: "true" # block merge on CRITICAL findings (when security review is on)
3634
security_block_on_high: "false" # block merge on HIGH findings (defaults to false)
3735

38-
# ---- runtime source pin ----
39-
droid_action_ref: "main"
40-
4136
droid-review:
4237
variables:
4338
FACTORY_API_KEY: $FACTORY_API_KEY
4439
GITLAB_TOKEN: $GITLAB_TOKEN
45-
# ---- Optional: add @droid fill mode -------------------------------------
46-
#
47-
# Uncomment the include below to also auto-fill new MRs' descriptions
48-
# from their diffs. The fill job fires on the same `merge_request_event`
49-
# trigger as the review job; together they form Factory Droid's GA GitLab
50-
# experience.
51-
#
52-
# include:
53-
# - remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/fill.yml"
54-
# inputs:
55-
# automatic_fill: "false" # true = fill every new MR automatically
56-
# droid_action_ref: "main"
57-
#
58-
# droid-fill:
59-
# variables:
60-
# FACTORY_API_KEY: $FACTORY_API_KEY
61-
# GITLAB_TOKEN: $GITLAB_TOKEN
62-
#
63-
# With automatic_fill="false", trigger fill manually per MR by either:
64-
# - writing "@droid fill" in the MR description, OR
65-
# - writing "@droid fill" in the MR title, OR
66-
# - adding the "droid:fill" label to the MR.
67-
#
68-
# After Droid fills the description, it strips the @droid fill token so
69-
# the next merge_request_event doesn't re-trigger.
70-
# -----------------------------------------------------------------------

‎gitlab/examples/README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,5 @@ Set both as **masked** CI/CD variables at the level you want the review
1919
to apply (project, subgroup, or top-level group).
2020

2121
For the full input reference (model overrides, security review,
22-
suggestion blocks, custom stage, etc.) see
23-
[`../templates/review.yml`](../templates/review.yml) or the docs at
22+
suggestion blocks, etc.) see the docs at
2423
[`docs/gitlab-setup.md`](../../docs/gitlab-setup.md).

‎gitlab/templates/review.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ spec:
5454
description: |
5555
Git ref (tag/branch/sha) of droid-action to clone at runtime.
5656
The same ref SHOULD match the `include: remote:` URL above.
57-
default: "dev"
57+
Internal: most users leave this at the default.
58+
default: "main"
5859
stage:
5960
description: "GitLab CI stage to assign the droid-review job to."
6061
default: "test"

0 commit comments

Comments
 (0)