docs(gitlab): add drop-in .gitlab-ci.yml samples under gitlab/examples/

Adds two consumer-facing sample files plus a README so users have a
canonical reference for what a Component-consuming .gitlab-ci.yml looks
like:

  * gitlab/examples/.gitlab-ci.minimal.yml — shortest possible, every
    default accepted, only the two required CI/CD variables wired.
  * gitlab/examples/.gitlab-ci.example.yml — annotated, every input
    spelled out with safe-default guidance, plus an optional
    @droid fill block (commented out) showing how to add fill.
  * gitlab/examples/README.md — table mapping each file to its use case
    and the variable-setup story.

Also updates docs/gitlab-setup.md:

  * Points readers at gitlab/examples/ instead of just inlining the
    snippet, so customers can clone the project, copy the file, done.
  * Drops the stale 'service account provisioning' reference now that
    the install-code-review skill no longer provisions SAs.
  * Tightens the GITLAB_TOKEN row to make the poster-identity story
    explicit: the token owner IS the poster, no API impersonation.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: factory-nizar

docs/gitlab-setup.md

@@ -15,23 +15,29 @@ droid
 > /install-code-review
 ```
 
-It detects GitLab, optionally provisions a branded `Factory Droid` service
-account, asks the configuration questions below, generates the
-`.gitlab-ci.yml`, and opens an MR / direct-commits to the target project(s).
+It detects GitLab, asks which account should be the poster of review
+comments (you supply its PAT as `GITLAB_TOKEN`), asks the configuration
+questions below, generates the `.gitlab-ci.yml`, and opens an MR /
+direct-commits to the target project(s).
 
 ## Manual installation
 
 ### 1. Prerequisites
 
-| Requirement                           | How to get it                                                                                                                                                     |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GitLab Maintainer role on the project | Repo admin grants you Maintainer (40)                                                                                                                             |
-| `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            |
-| `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**. |
+| Requirement                           | How to get it                                                                                                                                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GitLab Maintainer role on the project | Repo admin grants you Maintainer (40)                                                                                                                                                                    |
+| `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                                                   |
+| `GITLAB_TOKEN` CI/CD variable         | A personal access token with the `api` scope, owned by whichever account should post review comments. The token owner is the poster — there is no API impersonation. Add as **masked**, **unprotected**. |
 
 ### 2. Add the CI/CD Component
 
-Create or extend `.gitlab-ci.yml` in your project with:
+Drop-in samples live in [`gitlab/examples/`](../gitlab/examples/):
+
+- [`.gitlab-ci.minimal.yml`](../gitlab/examples/.gitlab-ci.minimal.yml) — shortest possible, accepts every default.
+- [`.gitlab-ci.example.yml`](../gitlab/examples/.gitlab-ci.example.yml) — annotated with every input.
+
+The minimal form looks like this; create or extend `.gitlab-ci.yml` in your project with:
 
 ```yaml
 include:

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

@@ -0,0 +1,70 @@
+# Example .gitlab-ci.yml showcasing the droid-action GitLab CI/CD Component.
+#
+# Drop this file (or its snippets) at the root of your GitLab project.
+# It defines a single `droid-review` job that runs Factory Droid's
+# automated code review on every merge_request_event.
+#
+# Prerequisites (one-time, configured via the GitLab UI or `glab`):
+#
+#   * FACTORY_API_KEY — masked CI/CD variable. Get one at
+#     https://app.factory.ai/settings/api-keys
+#
+#   * GITLAB_TOKEN    — masked CI/CD variable. A personal access token
+#     with `api` scope, minted by the GitLab user/account you want
+#     review comments to be posted from. The poster identity IS the
+#     owner of this token; there is no API impersonation. To switch
+#     posters later, replace the variable's value.
+#
+# Both variables can be set at the project, subgroup, or top-level
+# group level, depending on how widely you want the review to roll out.
+
+include:
+  # Pin to a release tag once droid-action publishes one. Until then,
+  # `main` tracks the latest stable cut. `droid_action_ref` below MUST
+  # match the ref in this URL so the template and the runtime source
+  # stay consistent.
+  - remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/review.yml"
+    inputs:
+      # ---- core review behavior ----
+      automatic_review: "true" # run on every MR event; "false" disables
+      review_depth: "deep" # "deep" (gpt-5.2 / high) or "shallow" (kimi-k2.6 / none)
+      include_suggestions: "true" # post code-suggestion blocks for high-confidence fixes
+
+      # ---- security review (parallel security-reviewer subagent) ----
+      automatic_security_review: "false" # enable to flag vulns alongside the regular review
+      security_block_on_critical: "true" # block merge on CRITICAL findings (when security review is on)
+      security_block_on_high: "false" # block merge on HIGH findings (defaults to false)
+
+      # ---- runtime source pin ----
+      droid_action_ref: "main"
+
+droid-review:
+  variables:
+    FACTORY_API_KEY: $FACTORY_API_KEY
+    GITLAB_TOKEN: $GITLAB_TOKEN
+# ---- Optional: add @droid fill mode -------------------------------------
+#
+# Uncomment the include below to also auto-fill new MRs' descriptions
+# from their diffs. The fill job fires on the same `merge_request_event`
+# trigger as the review job; together they form Factory Droid's GA GitLab
+# experience.
+#
+# include:
+#   - remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/fill.yml"
+#     inputs:
+#       automatic_fill: "false"   # true = fill every new MR automatically
+#       droid_action_ref: "main"
+#
+# droid-fill:
+#   variables:
+#     FACTORY_API_KEY: $FACTORY_API_KEY
+#     GITLAB_TOKEN: $GITLAB_TOKEN
+#
+# With automatic_fill="false", trigger fill manually per MR by either:
+#   - writing "@droid fill" in the MR description, OR
+#   - writing "@droid fill" in the MR title, OR
+#   - adding the "droid:fill" label to the MR.
+#
+# After Droid fills the description, it strips the @droid fill token so
+# the next merge_request_event doesn't re-trigger.
+# -----------------------------------------------------------------------

gitlab/examples/.gitlab-ci.minimal.yml

@@ -0,0 +1,12 @@
+# Minimal example: every default, just `include:` the Component.
+#
+# Requires FACTORY_API_KEY and GITLAB_TOKEN to be set as masked CI/CD
+# variables. See .gitlab-ci.example.yml for the annotated version.
+
+include:
+  - remote: "https://raw.githubusercontent.com/Factory-AI/droid-action/main/gitlab/templates/review.yml"
+
+droid-review:
+  variables:
+    FACTORY_API_KEY: $FACTORY_API_KEY
+    GITLAB_TOKEN: $GITLAB_TOKEN

gitlab/examples/README.md

@@ -0,0 +1,24 @@
+# GitLab examples
+
+Drop-in `.gitlab-ci.yml` samples for consuming the droid-action GitLab
+CI/CD Component.
+
+| File                     | When to use                                                                                                    |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `.gitlab-ci.minimal.yml` | Shortest possible — `include:` the review template, accept every default. Good starting point.                 |
+| `.gitlab-ci.example.yml` | Annotated. Every input spelled out with comments explaining what it does and what the safe defaults look like. |
+
+Both samples wire the same two required CI/CD variables:
+
+- `FACTORY_API_KEY` — get one at <https://app.factory.ai/settings/api-keys>.
+- `GITLAB_TOKEN` — a personal access token with `api` scope, owned by
+  whichever GitLab user/account should be the poster of review comments.
+  To change the poster later, replace this variable's value.
+
+Set both as **masked** CI/CD variables at the level you want the review
+to apply (project, subgroup, or top-level group).
+
+For the full input reference (model overrides, security review,
+suggestion blocks, custom stage, etc.) see
+[`../templates/review.yml`](../templates/review.yml) or the docs at
+[`docs/gitlab-setup.md`](../../docs/gitlab-setup.md).