Add available_on to foundational flows, with per-instance enablement on Dedicated

Problem

A foundational flow limited to GitLab.com, or behind a feature_flag, can't be rolled out to GitLab Dedicated customers one at a time: feature flags can't be enabled on Dedicated.

Change

  • New foundational flow attribute available_on: where the flow runs.

    Value Runs on
    :gitlab_com GitLab.com
    :self_managed Self-Managed
    :dedicated every GitLab Dedicated instance
    :dedicated_enabled_instances only the Dedicated instances GitLab has enabled it for, read from the AI gateway
    • Default: %i[gitlab_com self_managed dedicated], everywhere, as before.
    • Validated: not empty, only these values. :dedicated_enabled_instances can't be combined with :dedicated or :self_managed.
    • :dedicated comes from the instance's own setting, so a flow must not rely on it alone to restrict access.
  • With :dedicated_enabled_instances, on Dedicated the flow is on only where GitLab enabled it. That takes the place of its feature_flag there (feature flags can't be enabled on Dedicated). Opt-in follows the flow's maturity:

    feature_maturity Needs on Dedicated
    experimental, beta GitLab's enablement and the instance AI beta setting (the customer's opt-in)
    ga GitLab's enablement only
  • Only the AI gateway's answer can satisfy :dedicated_enabled_instances. A Self-Managed instance that sets gitlab_dedicated_instance still needs the AI gateway to list it, and the lookup fails closed.

  • New FoundationalFlow#enabled_for?(actor) (a namespace, or :instance): the single check for whether a flow is switched on. It is the flow's feature flag, as before, except where the per-instance gate applies here (per_instance_gate_applies?: Dedicated and :dedicated_enabled_instances).

  • New Ai::Catalog::FoundationalFlows::EnabledFlowsClient (in ee/lib): asks the GitLab-hosted AI gateway which flows GitLab has enabled for this instance.

    • Cached for 30 minutes.
    • If a lookup fails, it uses the last successful answer (kept for 1 day), so a short AI gateway outage doesn't turn flows off or refuse running sessions' checkpoints. With no previous answer, no flow is enabled (fails closed).
    • Trade-off: while every lookup fails, the last answer stays in use for up to a day after the last successful lookup, plus up to 5 minutes of cached failure. A refused or expired instance token counts as a failure too. A successful answer, including an empty one, replaces it at once.
  • The Dedicated check goes through Gitlab::Dedicated.feature_available?, with a new ai_flow_enablement Dedicated feature.

  • BLSA declares available_on: %i[gitlab_com]: the same behaviour as before. It adds :dedicated_enabled_instances in Enable BLSA per instance on GitLab Dedicated (!262270 - merged).

  • gitlab_hosted_runner_only is unchanged: it describes where the flow's job runs, not where the flow is offered.

  • blocked_by_feature_flag? is renamed blocked_for?: it covers available_on and GitLab's per-instance enablement, not only the flag.

    • The internal names built on it follow: policy condition foundational_flow_blocked, CreateWorkflowService#check_flow_blocked, RunService#flow_blocked?, WorkflowsInternal#forbid_blocked_flow!.
    • Client-facing messages and reasons (flow is disabled by a feature flag, :flow_disabled_by_feature_flag) are unchanged.
  • ItemConsumerPolicy splits the check:

    • foundational_flow_blocked_by_settings (available_on, the feature flag, or the instance beta setting on Dedicated) prevents reading, managing and running the consumer;
    • foundational_flow_blocked (which adds GitLab's per-instance lookup, score: 10 so it is evaluated after the cheaper conditions) prevents only running it, so the lookup alone (flow not enabled, or the lookup failed) doesn't hide the consumer from its owners.
  • The checkpoint save guard (forbid_blocked_flow!) also covers flows without a feature_flag, so a blocked flow stops its running sessions whatever blocks it.

Impact

No flow uses :dedicated_enabled_instances here, so no behaviour changes. No flow without a feature flag is blocked anywhere, so the wider checkpoint guard changes nothing either.

Flow GitLab.com Self-Managed Dedicated
Default available_on (every flow except BLSA) unchanged unchanged unchanged
BLSA (available_on: %i[gitlab_com]) unchanged (flag per group) unchanged (off) unchanged (off)
A future flow with :dedicated_enabled_instances its feature_flag, if it lists :gitlab_com off on only where GitLab enabled it, plus the opt-in above

Using this for another flow

For flows that run only on GitLab.com today: available_on: %i[gitlab_com], or a feature flag that is off by default and not turned on for Self-Managed. A flow that runs on Self-Managed today, even behind a flag, must not use it. Adding a flow to the Duo Workflow Service's gated flows refuses it to every instance GitLab has not enabled, Self-Managed included.

  1. Set the flow's available_on to the deployments it runs on, with :dedicated_enabled_instances in place of :dedicated and without :self_managed, e.g. available_on: %i[gitlab_com dedicated_enabled_instances]. Validation rejects the other combinations.
  2. Add the flow id to GATED_FLOWS and its instance uids in feat(dws): enable gated flows per instance for ... (gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7508 - merged).
    • The AI gateway only lists flows that are there. A flow missing there never turns on: its id is absent from the answer, which looks like the normal "not enabled" case.
  3. Switch the flow's own feature flag checks elsewhere in Rails to enabled_for?. BLSA example: Enable BLSA per instance on GitLab Dedicated (!262270 - merged).
  4. If the flow has its own model-selection entry, add it like BLSA's in Ai::FeatureSetting (see Enable BLSA per instance on GitLab Dedicated (!262270 - merged)).

Tests

Spec Covers
foundational_flow_spec.rb available_on validation: unknown value, empty, :dedicated_enabled_instances with :dedicated or :self_managed
Every available_on value on GitLab.com, Self-Managed and Dedicated
:dedicated_enabled_instances on Dedicated: GitLab enablement and the beta setting for experimental and beta, GitLab enablement only for ga, no AI gateway call with the beta setting off, fails closed when the AI gateway is down, licensing still applies
Self-Managed with gitlab_dedicated_instance set: blocked when the AI gateway returns [] or fails
available_on: %i[gitlab_com] runs only on GitLab.com; the default runs everywhere with no AI gateway call
enabled_flows_client_spec.rb Instance auth, timeout, GitLab-hosted AI gateway only, caching, failing closed, offline license; after a successful lookup, a failure returns the last good answer; a failure does not refresh it, and it is no longer used a day after the last success; a successful empty answer replaces it
item_consumer_policy_spec.rb When only GitLab's per-instance lookup blocks the flow, owners can still read and manage the consumer, and only running it is blocked; flow settings still block all three
workflows_internal_spec.rb A flow without a feature flag that is not available on this deployment gets its checkpoint save refused

How to set up and validate

Tested on its own on 2026-10-21 at bb94e7a022d5, on master 9687069f87d1. Later commits:

  • dd3786918cd5 and dfd6fd0e0c74 change only specs.
  • 5c60c55e45bd splits the consumer policy check, a6d9f2dae235 adds a coverage spec, and 0716ba517316 moves the lookup to ee/lib. None of them changes blocked_for?, so flow availability (the end-to-end rows below) is unchanged; the changed specs were re-run at 0716ba517316.
Check Result
foundational_flow_spec.rb, BLSA definition_spec.rb, fetch_enabled_flows_service_spec.rb at bb94e7a022d5 245, 38 and 17 examples, 0 failures
foundational_flow_spec.rb and fetch_enabled_flows_service_spec.rb at dfd6fd0e0c74 264 examples, 0 failures. Each new spec fails when the code is changed to break what it covers (refresh on failure; a longer expiry)
project_spec.rb risk assessment block at a6d9f2dae235 6 examples, 0 failures
Changed specs and the specs master's 64f72278 touched, at cc61fd33f6fe (on master d5ac995b4573) 1,570 examples, 0 failures; RuboCop clean; scripts/undercoverage reports nothing uncovered in this MR's changes
Changed specs at 0716ba517316 (enabled_flows_client_spec, foundational_flow_spec, groups/update_service_spec, item_consumer_policy_spec, flow_execution_authorizer_spec) 633 examples, 0 failures; RuboCop clean on the changed files
All 16 foundational flows vs plain master (Self-Managed, Dedicated with the beta setting on and off, GitLab.com) identical availability for every flow (64 rows each); no AI gateway calls
CI at dd3786918cd5 (tier 1: the specs for the changed files) passed; only rspec:undercoverage, which is allowed to fail, fails (see below). The full suite runs at tier 3, after approval

End to end on 2026-10-21 with Enable BLSA per instance on GitLab Dedicated (!262270 - merged), Allow GitLab-hosted Dedicated runners for trust... (!262250 - merged) and the AI gateway and Duo Workflow Service MRs, on a Dedicated-like GDK:

Check Result
Allowlisted Dedicated instance real BLSA scan finished on a GitLab-hosted runner
AI gateway stopped after a good lookup the flow stays available; a running session saved all its checkpoints (109 of 109)
AI gateway stopped, no previous answer flow hidden (fails closed)

End to end again on 2026-10-27, on a Dedicated-like GDK: a local merge of this MR at 0716ba517316 with Enable BLSA per instance on GitLab Dedicated (!262270 - merged) at 67b028e09171, plus ai-assist main 628356d5e37c with feat(duo-workflow): add per-tool allowed_flows,... (gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7510 - merged) at cfa804eee65a, enforcement on:

Case Result
Dedicated, beta on, instance on GitLab's allowlist A real BLSA scan finished on a GitLab-hosted runner, SAST report with 1 finding
Same, instance off the allowlist (every customer setting still on) Not offered and API start refused in Rails; the Duo Workflow Service refuses the token ("Flow 'bl_security' is not enabled for this instance")
Allowlisted, beta setting off Not offered, API start refused, no workflow created
Self-Managed Blocked, API start refused, no workflow created
Only the per-instance lookup blocks the flow (instance off the allowlist, or the AI gateway down) A group owner can still read and manage the project consumer; running it is refused

rspec:undercoverage (allowed to fail) flagged Project#risk_assessment_dap_available? at dd3786918cd5: its &. nil branch had no spec. a6d9f2dae235 adds one for a missing flow definition.

Setup

  1. Start a GDK set up as GitLab Dedicated, not GitLab.com, with Ultimate and Duo:
    ApplicationSetting.current.update!(gitlab_dedicated_instance: true)
  2. Run the AI gateway and the Duo Workflow Service from feat(dws): enable gated flows per instance for ... (gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7508 - merged). Set these on both services:
    DUO_WORKFLOW_AUTH__ENFORCE_FLOW_ENABLEMENT=true
    DUO_WORKFLOW_AUTH__ENABLED_FLOW_INSTANCE_UIDS='{"bl_security": ["<instance uid>"]}'
    In GDK with self-signed tokens, the instance uid is ApplicationSetting.current.uuid.
  3. Turn on the instance AI beta setting: Admin > GitLab Duo > Configuration > Feature preview.
  4. With this MR alone, no flow uses :dedicated_enabled_instances: check that every flow's availability is unchanged.
  5. To see the gate work, use Enable BLSA per instance on GitLab Dedicated (!262270 - merged), where BLSA adds :dedicated_enabled_instances.

Context

Related to https://gitlab.com/gitlab-org/gitlab/-/work_items/633855+

Edited by Meir Benayoun

Merge request reports

Loading
Loading