Skip to content

Commit 6f05311

Browse files
factory-nizarfactory-droid[bot]
factory-nizar
and
factory-droid[bot]
committed
docs(gitlab): add gitlab-setup.md and README section for GitLab CI/CD Component
Documents the manual installation flow for the new GitLab CI/CD Component (`gitlab/templates/review.yml`): prerequisites, full inputs table, what the pipeline produces, how the two-pass review works, what is intentionally not yet supported (comment triggers, fill mode, scheduled scans), and troubleshooting steps. README now has a short GitLab section that points to the full guide. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
1 parent 1c6a2a5 commit 6f05311

2 files changed

Lines changed: 171 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,28 @@ The guided flow will:
3838

3939
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.
4040

41+
### GitLab
42+
43+
GitLab support ships as a **GitLab CI/CD Component** under `gitlab/templates/review.yml`. It delivers the same automatic two-pass code review and parallel security-reviewer subagent, with inline MR comments, a sticky tracking note, and `.droid-debug/` artifacts.
44+
45+
Minimal `.gitlab-ci.yml`:
46+
47+
```yaml
48+
include:
49+
- remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/review.yml"
50+
inputs:
51+
automatic_review: "true"
52+
automatic_security_review: "false"
53+
review_depth: "deep"
54+
55+
droid-review:
56+
variables:
57+
FACTORY_API_KEY: $FACTORY_API_KEY
58+
GITLAB_TOKEN: $GITLAB_TOKEN
59+
```
60+
61+
Full setup, available inputs, and troubleshooting live in [`docs/gitlab-setup.md`](docs/gitlab-setup.md). Comment-triggered modes (`@droid review` / `@droid fill`) are not yet supported on GitLab — they require platform features GitLab does not expose natively.
62+
4163
### Manual Setup
4264

4365
If you prefer to wire things up by hand:

‎docs/gitlab-setup.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# GitLab Setup
2+
3+
This action ships a **GitLab CI/CD Component** that delivers the same
4+
automated code-review experience as the GitHub action on GitLab merge
5+
requests (MRs). The component runs on every `merge_request_event` pipeline,
6+
posts inline comments on the diff, maintains a sticky tracking note, and
7+
optionally runs a security-focused subagent in parallel.
8+
9+
## Quick start with `/install-code-review`
10+
11+
The fastest path is the guided installer built into the Droid CLI:
12+
13+
```bash
14+
droid
15+
> /install-code-review
16+
```
17+
18+
It detects GitLab, optionally provisions a branded `Factory Droid` service
19+
account, asks the configuration questions below, generates the
20+
`.gitlab-ci.yml`, and opens an MR / direct-commits to the target project(s).
21+
22+
## Manual installation
23+
24+
### 1. Prerequisites
25+
26+
| Requirement | How to get it |
27+
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28+
| GitLab Maintainer role on the project | Repo admin grants you Maintainer (40) |
29+
| `FACTORY_API_KEY` CI/CD variable | Generate at <https://app.factory.ai/settings/api-keys>; add as **masked**, **unprotected** variable at the project, subgroup, or top-level group level |
30+
| `GITLAB_TOKEN` CI/CD variable | A personal or service-account access token with the `api` scope. Required so the MCP server can post comments back to the MR. Add as **masked**, **unprotected**. |
31+
32+
### 2. Add the CI/CD Component
33+
34+
Create or extend `.gitlab-ci.yml` in your project with:
35+
36+
```yaml
37+
include:
38+
- remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/review.yml"
39+
inputs:
40+
automatic_review: "true"
41+
automatic_security_review: "false"
42+
review_depth: "deep"
43+
include_suggestions: "true"
44+
security_block_on_critical: "true"
45+
security_block_on_high: "false"
46+
droid_action_ref: "main"
47+
48+
droid-review:
49+
variables:
50+
FACTORY_API_KEY: $FACTORY_API_KEY
51+
GITLAB_TOKEN: $GITLAB_TOKEN
52+
```
53+
54+
> Pin both the `include:` URL ref and `droid_action_ref` to a release tag
55+
> (e.g. `v1`) once one is published. They MUST match — the URL pin
56+
> resolves the template at parse time, `droid_action_ref` clones the same
57+
> source at runtime.
58+
59+
### 3. Push an MR
60+
61+
Open or push to an MR. The next `merge_request_event` pipeline will run
62+
the `droid-review` job. Expect ~5-10 minutes for a typical change.
63+
64+
## Inputs
65+
66+
| Input | Default | Description |
67+
| ---------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
68+
| `automatic_review` | `"true"` | Run code review automatically on every MR pipeline. |
69+
| `automatic_security_review` | `"false"` | Run a parallel security-focused subagent on every MR pipeline. Findings are prefixed `[security]` and posted alongside code-review comments. |
70+
| `review_depth` | `"deep"` | `"deep"` (thorough) or `"shallow"` (fast). |
71+
| `review_model` | `""` | Override the model. Empty = use depth preset. |
72+
| `reasoning_effort` | `""` | Override reasoning effort. Empty = use depth preset. |
73+
| `include_suggestions` | `"true"` | Include code suggestion blocks in review comments when the fix is high-confidence. |
74+
| `security_block_on_critical` | `"true"` | Block merge on CRITICAL security findings. (Mirrors GitHub action; surface-level parity.) |
75+
| `security_block_on_high` | `"false"` | Block merge on HIGH security findings. (Mirrors GitHub action; surface-level parity.) |
76+
| `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. |
77+
| `droid_action_repo` | `https://github.com/Factory-AI/droid-action.git` | Override if you mirror droid-action privately. |
78+
| `droid_action_ref` | `"dev"` | Git ref of droid-action to clone at runtime. Should match the `include: remote:` URL ref. |
79+
| `stage` | `"test"` | GitLab CI stage to assign the `droid-review` job to. |
80+
81+
## What you get
82+
83+
Each MR pipeline produces:
84+
85+
- **Inline review comments** anchored to the relevant diff lines, posted in a
86+
single batched `submit_review` call. Findings are prefixed with priority
87+
tags (`P0`, `P1`, `P2`, `P3`) and `[security]` for security findings.
88+
- **A sticky tracking note** on the MR with pipeline + job links, telemetry
89+
(`N turns • Xm Ys`), session IDs, and a security badge when
90+
`automatic_security_review` is enabled.
91+
- **Debug artifacts** at `.droid-debug/` (prompts, candidate JSON, raw
92+
stream-json logs) retained for 1 week.
93+
- **A custom droid library** copied from
94+
`$DROID_ACTION_DIR/.factory/droids` into `~/.factory/droids` on the
95+
runner, so subagents like `security-reviewer` are reachable.
96+
97+
## How it works
98+
99+
The pipeline runs in two passes:
100+
101+
1. **Pass 1 (candidates)** — Droid Exec reads the MR diff, description, and
102+
existing comments, then writes `/tmp/droid-prompts/review_candidates.json`
103+
with candidate findings. The security-reviewer subagent runs in parallel
104+
if `automatic_security_review` is on. **No MR mutations** happen in this
105+
pass — the MR-write tools are excluded from `--enabled-tools`.
106+
2. **Pass 2 (validator)** — Droid Exec rereads the candidates, filters out
107+
duplicates and low-confidence findings, and batches all approved comments
108+
into a single `gitlab_mr___submit_review` call. The sticky note is
109+
updated via `gitlab_mr___update_tracking_note`.
110+
111+
A small GitLab MCP server (`src/mcp/gitlab-mr-server.ts`) is launched on
112+
the runner to expose those two write tools.
113+
114+
## What's not yet supported
115+
116+
These exist in the GitHub action but require platform features GitLab
117+
does not currently expose, and are not part of Phase 1:
118+
119+
- **Comment-triggered modes** (`@droid review`, `@droid security`,
120+
`@droid fill`). GitLab does not fire CI pipelines on note events.
121+
Requires a Factory-hosted webhook receiver that turns note webhooks
122+
into `POST /projects/:id/trigger/pipeline` calls. Planned as a follow-up.
123+
- **`@droid fill` (MR description fill).** Depends on the comment trigger
124+
above.
125+
- **Scheduled full-repo security scans.** Tracked separately.
126+
127+
## Troubleshooting
128+
129+
| Symptom | Likely cause | Fix |
130+
| --------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
131+
| 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 |
132+
| `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 |
133+
| `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) |
134+
| 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 |
135+
| Pipeline times out | Very large MR | Set `review_depth: "shallow"` for faster feedback |
136+
137+
## Self-hosted GitLab
138+
139+
The component reads `CI_API_V4_URL` and `CI_SERVER_URL` from the standard
140+
GitLab CI environment. Self-managed GitLab works as long as your runner
141+
can:
142+
143+
- Reach `https://app.factory.ai/cli` to install the Droid CLI
144+
- Reach `https://github.com/Factory-AI/droid-action.git` (or your private
145+
mirror, via `droid_action_repo`)
146+
- Reach `https://raw.githubusercontent.com/...` for the `include: remote:`
147+
148+
Mirror droid-action internally and set `droid_action_repo` + `droid_action_ref`
149+
accordingly if your runners cannot reach GitHub.

0 commit comments

Comments
 (0)