[FF] onboarding_guide_agent -- Onboarding agent foundational chat agent

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Summary

Roll out the Onboarding agent, currently behind the onboarding_guide_agent feature flag.

The flag controls whether the Onboarding agent (AI Catalog item 1003979) appears in the GitLab Duo Chat agent list. It is introduced in !245452 (merged) and ships default off in 19.4 as an experiment (registration merged 2026-08-20; missed the 19.3 cut).

Important

Current state (2026-09-18): enabled on GitLab.com for four GitLab-owned groups only (gitlab-org, gitlab-com, gitlab-learn-labs, gl-demo-ultimate-cguitarte) since 2026-09-13. It was enabled globally 2026-09-03 → 2026-09-13 by mistake and scoped back to match the Trust & Safety closed-beta acceptance (gitlab-com/gl-security/security-operations/trust-and-safety/operations#2244). Closed-beta customer groups are added by name, one batch per wave. Default-off on self-managed and Dedicated. Widening beyond named groups waits on https://gitlab.com/gitlab-org/gitlab/-/work_items/628148 (R1 billable-list entry, R2 Free/trial exclusion at the finder).

  • DRI: @nfrye
  • Team Slack channel: #CX-Engineering

Note

Process and guidance live in the docs. This issue is just the commands and a place to track the rollout. Feature flag controls and feature flag lifecycle.

Actor semantics

The gate is applied in ee/app/graphql/resolvers/ai/foundational_chat_agents_resolver.rb:

  • On GitLab.com, the actor is the caller's governing root namespace, so --group= targeting works and individual top-level groups can be opted in.
  • On GitLab Self-Managed, there is no meaningful namespace actor, so a nil actor is passed and the flag acts as a global gate.

What could go wrong?

Blast radius is small. The flag only controls visibility of one experimental agent in the chat agent picker. The agent's tool grant is 31 tools including 8 writes limited to planning items (create_work_item, create_epic, create_issue_note, create_work_item_note, update_work_item, update_issue, update_epic, create_plan), each gated on explicit user confirmation before the write. It cannot create, edit, or commit files, modify pipelines, or change project settings; MCP is off. So there is no data-loss path on repositories or CI. The main risks are (a) exposing the agent to a namespace before the Catalog-side prompt changes are confirmed, and (b) the picker path (onboarding_guide/v1) being non-billable until https://gitlab.com/gitlab-org/gitlab/-/work_items/628148 lands — Trust & Safety has gated public beta on it.

Rollout

Run all production ChatOps commands in #production. Background: incremental rollout process, feature actors. Commands below are shown with a $ shell prompt; paste everything after it.

Non-production

$ /chatops gitlab run feature set onboarding_guide_agent 50 --actors --dev --pre --staging --staging-ref
$ /chatops gitlab run feature set onboarding_guide_agent true --dev --pre --staging --staging-ref

Production, percentage rollout (wait at least 15 min between steps, watch dashboards):

$ /chatops gitlab run feature set onboarding_guide_agent <percentage> --actors

Or target specific top-level groups instead, which is the expected path for this experiment and the closed beta:

$ /chatops gitlab run feature set --group=<group-path> onboarding_guide_agent true

Rollout history

Date Step Scope By
2026-08-28 1 gl-demo-ultimate-cguitarte, gitlab-org (production); dev/staging global @eduardobonet (chatops on DRI's behalf)
2026-08-29 2 gitlab-learn-labs @eduardobonet
2026-08-31 2 gitlab-com (approved by Manav Khurana) @eduardobonet
2026-09-03 3 Global on GitLab.com — in error; the plan changed to closed beta on 4 Sep and the flag did not follow (see 15 Sep note) @lduncalfe
2026-09-13 4 Scoped back to the four groups above (13:51–13:53 PDT; logs #64256/#64257) @lduncalfe
w/c 2026-09-22 5 Closed-beta customer groups, one batch per wave — gitlab-com/customer-success/cx-engineering/cx-platform-engineering/agents/onboarding-agent#66 (confidential) @lduncalfe
TBD 6 Public beta — only after R1/R2 in https://gitlab.com/gitlab-org/gitlab/-/work_items/628148 are live

Before global rollout

Confirm the relevant gotchas before going to 100%. See enabling a feature for GitLab.com:

  • Docs and version history updated — agent page published with !245452 (merged); sidebar nav via docs-gitlab-com!2583 (1 Sep).
  • Catalog-side secret-safety guidance confirmed applied to item 1003979 (v2.0.0, 19 Aug).
  • Experiment feedback captured in #606350.
  • Trust & Safety gate for public beta: https://gitlab.com/gitlab-org/gitlab/-/work_items/628148 — R1 (onboarding_guide/v1 on the billable list, customers-gitlab-com#18668) and R2 (Free/trial exclusion at foundational_chat_agents_finder.rb).
  • Create the release note. File doc/releases/19/gitlab-19-X-released/onboarding_guide.md in gitlab-org/gitlab using the Release Notes Item MR template, in the milestone where this flag goes default-on — not before. Per the template, release notes merge only when the feature is deployed and enabled. Set the milestone on the MR (Danger flags MRs without one), add a Technical Writer as reviewer immediately, and use level: secondary unless we're also adding a features.yml entry in www-gitlab-com. Precedent: Support Assistant's release note (!243290 (closed)) sat 43 days without approval and missed its release.

Cleanup

Remove the flag once deemed stable. See cleaning up. Remove the flag and its YAML definition from the codebase, then:

$ /chatops gitlab run release check <merge-request-url> <milestone>
$ /chatops gitlab run feature delete onboarding_guide_agent --dev --pre --staging --staging-ref --production

Rollback

$ /chatops gitlab run feature set onboarding_guide_agent false                                              # production
$ /chatops gitlab run feature set onboarding_guide_agent false --dev --pre --staging --staging-ref          # non-production

Per-group disable (preferred during the closed beta — one customer, not everyone):

$ /chatops gitlab run feature set --group=<group-path> onboarding_guide_agent false
Edited by 🤖 GitLab Bot 🤖