Add opt-in fail-closed default for background tool governance
What does this MR do and why?
On the background surface, an un-ruled write or execute tool resolves to Allow. A group that wants Duo Developer locked down has to write a Background rule for every tool.
This adds duo_workflow_background_fail_closed, a default-off beta flag checked on the root group. With the flag on, those un-ruled tools resolve to Deny instead.
- Reads and
notify_me_whenstay Allow. - Un-ruled tools are put in
denied_toolsby name, not only dropped with their privilege. There are two reasons:- A partly ruled group (for example only
edit_fileallowed) keeps its privilege. Without the names, the other tools in that group would be in no list, and the flow would halt on its first call to one of them. - The GitLab MCP spelling of a denied catalog tool, such as
gitlab_create_issue, is only reached throughdenied_tools.
- A partly ruled group (for example only
run_mcp_toolskeeps its group default. It has no catalog tools, so denying it would drop the privilege that pre-approves read-only MCP tools. MCP-only tools fail closed one by one instead.- A project rule can't loosen the default. A project Background Allow on a tool the default denies is rejected, and an older one is ignored, the same as under a group Deny rule.
- The settings page shows Deny in the Background column for those tools, through the same
background_effectivecall that enforcement uses. - The helper also requires
duo_workflow_background_tool_governance, so the page never shows Deny where background rules aren't enforced.
With duo_workflow_block_start_on_denied_group on and no Background rules, Duo Developer is refused at start with the existing message. Behaviour with the flag off is unchanged.
The flag only changes the default on the background surface, so it has no effect unless duo_workflow_background_tool_governance is on. With that flag off, Developer reads Web rules, as on master.
No docs or changelog in this MR. The flag is default-off and will only be enabled for a test group. The docs and release note land before the first customer group, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/636652.
Out of scope:
- Third-party and client-injected MCP tools. Governance covers the tools served by GitLab's own MCP server.
- Clamping the workflow row's declared
agent_privilegeson the background surface. This is unchanged frommaster. Every tool Duo Developer uses is in the Rails tool map, so the denied ones are stripped throughdenied_tools. Flows that use tools missing from the map need this before they come under governance (https://gitlab.com/gitlab-org/gitlab/-/work_items/607357). - The shell route. Allowing
run_commandlets the flow write files, commit and open MRs through the shell, even with those tools denied. This is the shell split in https://gitlab.com/gitlab-org/gitlab/-/work_items/633005.
References
- https://gitlab.com/gitlab-org/gitlab/-/work_items/606829
- Rollout: https://gitlab.com/gitlab-org/gitlab/-/work_items/636652
- Group-level setting to replace the flag: https://gitlab.com/gitlab-org/gitlab/-/work_items/636653
- Moving tool governance to the governing namespace: https://gitlab.com/gitlab-org/gitlab/-/work_items/637740
- Background governance rollout: https://gitlab.com/gitlab-org/gitlab/-/work_items/613787
- Block at start: !258400 (merged)
Screenshots or screen recordings
No UI code changes. The Background column shows Deny for un-ruled write and execute tools when the flag is on. The GDK results are below.
The group gitlab-duo already had three rules:
create_merge_requestdenied on every surfacecreate_commitdenied on Web only- MCP
searchdenied on Web only
duo_workflow_background_tool_governance and duo_workflow_block_start_on_denied_group were on for the group in every run. "Flag off" and "Flag on" below refer to duo_workflow_background_fail_closed only.
Assigning Duo Developer on an issue
Flag off (same as master) |
Flag on, no Background rules |
|---|---|
Policy sent to DWS / settings page Background column, with no Background rules
| Tool | master |
Flag off | Flag on |
|---|---|---|---|
read_file, list_issues, notify_me_when |
allow / Allow | allow / Allow | allow / Allow |
create_file_with_contents, edit_file, mkdir, run_tests, run_command |
allow / Allow | allow / Allow | deny / Deny |
run_git_command, create_issue, create_commit (Web-only deny) |
allow / Allow | allow / Allow | deny / Deny |
create_merge_request (explicit deny) |
deny / Deny | deny / Deny | deny / Deny |
| GitLab MCP tools denied | 1 | 1 | 16 (the write ones) |
| Pre-approved privileges | all 7 | all 7 | read_only_gitlab, read_only_files, run_mcp_tools |
Partial opt-in, flag on
| Background Allow rules | Start | Policy |
|---|---|---|
edit_file, run_command |
starts | The other three file tools are denied by name |
All four file tools and run_command |
starts | Those five are allowed. run_git_command, create_issue and create_commit stay denied. Developer doesn't use them. |
How to set up and validate locally
- Pick a top-level group with Duo Developer enabled, for example
gitlab-duo. In the Rails console:group = Group.find_by_full_path('gitlab-duo') Feature.enable(:duo_workflow_background_tool_governance, group) Feature.enable(:duo_workflow_block_start_on_denied_group, group) Feature.enable(:duo_workflow_background_fail_closed, group) - Open the group's AI tool rules settings page. The Background column shows Deny for write and execute tools you haven't set, and Allow for read tools.
- Assign the Duo Developer service account to an issue in a project of that group. The account replies that an administrator denied the tools the flow needs.
- On the settings page, set
run_commandand the four file tools (create_file_with_contents,edit_file,mkdir,run_tests) to Allow under Background. Assign Developer again. It starts. - Disable
duo_workflow_background_fail_closedfor the group. Assigning Developer starts it with no Background rules, as onmaster.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.