## Summary Roll out [Orbit's read-only openCypher-based frontend](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/issues/1258) behind `orbit_gql_queries`. Rails checks this default-off flag before it forwards GQL requests to Workhorse. The check covers REST, MCP, and the agent-command endpoint. JSON continues to exist as the default. The flag can target a user or a root group. The root-group gate requires the Developer role or higher in that group or one of its subgroups. The flag does not change query authorization. Command discovery advertises GQL even when the flag is off. Rails rejects GQL requests from users outside the enabled cohort. - DRI: @aalgutifan - Team Slack channel: `#g_knowledge_graph` - Orbit implementation: https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/merge_requests/2460 - Rails MR: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/256465 This issue tracks gradual enablement on GitLab.com. Removing the flag is a separate release step. ## What could go wrong? GQL requests could fail or run more slowly than equivalent JSON queries. Watch query errors and latency for the enabled cohort. Agents can discover GQL before they have access. They can also retain GQL queries after rollback. Rails must reject those requests when the flag is off, even after clients refresh their catalogs. The flag must not change authorization or reinterpret JSON requests as GQL. ## Events - [Exceptions with orbit_gql_queries enabled](https://log.gprd.gitlab.net/app/discover#/?_g=\(time:\(from:now-1d,to:now\)\)&_a=\(index:'7092c4e2-4eb5-46f2-8305-a7da2edad090',query:\(language:kuery,query:'json.exception.feature_flag_states.keyword:%22orbit_gql_queries:1%22'\)\)) - [Events with orbit_gql_queries enabled](https://log.gprd.gitlab.net/app/discover#/?_g=\(time:\(from:now-1d,to:now\)\)&_a=\(index:'7092c4e2-4eb5-46f2-8305-a7da2edad090',query:\(language:kuery,query:'json.feature_flag_states:%22orbit_gql_queries:1%22'\)\)) - [Feature flag logging guidance](https://docs.gitlab.com/development/feature_flags/#logging) ## Rollout Run production commands in [#production](https://gitlab.slack.com/archives/C101F3796), then share results in `#g_knowledge_graph`. Follow the [incremental rollout process](https://docs.gitlab.com/development/feature_flags/controls/#process). ### Prerequisites - [ ] Merge the Orbit implementation and publish a Go protobuf module version containing the GQL enum. - [ ] Pin that version in the Rails MR's Workhorse go.mod and go.sum. Run its routing tests. - [ ] Deploy compatible Orbit, Rails, and Workhorse versions with the flag off. - [ ] Verify JSON and named queries still work. Verify Rails rejects GQL while the flag is off. - [ ] Verify raw and TOON command catalogs advertise GQL regardless of flag state. ### Staging ```shell /chatops gitlab run feature set --user=aalgutifan orbit_gql_queries true --staging ``` - [ ] Run GQL through REST, MCP, and the agent-command endpoint for the enabled user. - [ ] Verify Rails rejects GQL for a disabled user on all three endpoints. Verify JSON still works for both users. - [ ] Test a root-group cohort, including subgroup-only members. Developer+ members should gain GQL access. Reporters should not gain access through that group gate. - [ ] Disable the flag and verify rollback before production enablement. ### Production ```shell /chatops gitlab run feature set --user=aalgutifan orbit_gql_queries true ``` - [ ] Repeat the staging checks for the initial user. - [ ] Expand to agreed users or root groups after reviewing errors and latency. Wait at least 15 minutes between steps. Use user or root-group actors, not project actors. Prefer explicit cohorts while the flag supports both actor types. ## Before global rollout - [ ] Complete the full security checks and agent evaluations tracked by the feature issue. - [ ] Run the Rails request specs against PostgreSQL and the Workhorse tests against the published protobuf version. - [ ] Update API documentation and record the deployed versions and cohort results here. - [ ] Confirm rollback leaves JSON and named queries available. - [ ] Review whether a production change-management issue is required before global enablement. ## Cleanup Once stable, remove the flag and its YAML definition in a follow-up MR. Removing JSON support is separate work and must wait for client migration and evaluation results. Follow the [feature flag cleanup process](https://docs.gitlab.com/development/feature_flags/controls/#cleaning-up). ## Rollback ```shell /chatops gitlab run feature set orbit_gql_queries false /chatops gitlab run feature set orbit_gql_queries false --staging ``` Verify new GQL requests are rejected in Rails. Command catalogs still advertise GQL after refresh. JSON and named queries must remain available. <!--AI-Sessions dir: ~/.pi/agent/sessions/--Users-aaronalgutifan-Repos-kg-wt-orbit-gql-transport--/ 2026-09-17T17-02-37-382Z_01a0b051-f945-768f-b409-8e34f738ddd9.jsonl (2026-09-17)-->