## Overview The Duo Agent Platform requires a robust identity system to enable agents to operate within GitLab with proper attribution and user interaction capabilities. This design outlines the approach for creating and managing agent service accounts that serve dual purposes in the platform. ## Core Requirements These requirements are applicable to both Duo Flows (created in the catalog using the flow editor) and Third Party Flows (created in the catalog using the YAML editor) ### 1. Audit Trail and Attribution When agents modify records (issues, merge requests, code, etc.), we need to maintain clear audit trails by recording: - Which specific agent performed the action - The agent's unique identifier and display name - Timestamp and context of the modification - The user who initiated the agent action ### 2. User Interaction and Discoverability Agents must be addressable by users through familiar GitLab interaction patterns: - **@mention functionality**: Users can explicitly invoke agents in comments using `@agent-name` - **Assignment capabilities**: Agents can be assigned to issues, merge requests, and other work items - **Direct invocation**: Clear UI elements for triggering specific agent workflows ## Current State and Limitations ### Flow Triggers (18.3) Our existing Flow Triggers feature allows users to specify service accounts for invoking Third Party Flows (agents), but has significant limitations: **Current Capabilities:** - Users can manually create service accounts for agent workflows - Service accounts can be associated with specific flows **Key Limitations:** 1. **Manual Creation Overhead**: Users must manually provision each service account, creating friction in agent adoption 2. **Group-Level Isolation**: Service accounts are scoped to individual groups, preventing cross-group agent usage 3. **Permission Barriers**: Requires maintainer-level access to create service accounts, limiting self-service capabilities 4. **Scalability Issues**: Manual process doesn't scale as agent usage grows across the platform ### Composite Identity (18.4) The Composite Identity feature enables service accounts to assume user permissions dynamically: **How It Works:** - Service accounts can act on behalf of the triggering user - Inherited permissions match the user's access level across all GitLab objects - Maintains security boundaries while enabling flexible agent operations **Important Constraint:** Service accounts configured for composite identity cannot simultaneously function as traditional service accounts for direct resource access. ## Proposed Solutions ### Chosen First iteration 1. We will pull in first party (https://gitlab.com/gitlab-org/gitlab/-/issues/577667) and third party foundational agents (https://gitlab.com/gitlab-org/gitlab/-/issues/577668) into the catalog from Duo Workflow Service 2. For custom agents, the publisher will be able to pick a unique flow name that will be used to name the service account in step 3. 3. The **group owner** will be able to add these public flows as well as custom organisational flows to the top level namespace. At this point in time we will automatically create a service account (with composite identity enabled) using a combination of group name, flow name and a unique identifier. (https://gitlab.com/gitlab-org/gitlab/-/issues/577669) 4. A **project maintainer+** needs to go into the project and add the flow. At this point in time we will: 1. Add the service account to be a developer on the project 2. Give the ability for the user to create triggers for the project (such as issue/mr assignment, `@mention`, and mr reviewer). (https://gitlab.com/gitlab-org/gitlab/-/issues/577680) 5. When **developer+** users need to interact with the agent, they will `@mention`, assign, etc the agent service account and that will then correspondingly trigger the agent. (as it works in 18.5) 6. We will generate the composite identity token for the service account and then start a CI job. (as it works in 18.5) ### Originally proposed alternatives We proposed two distinct approaches to streamline service account creation and management: <details> <summary>Option 1: Instance-Level Global Service Accounts</summary> **Implementation Approach:** When a user registers a flow, the system automatically creates an instance-level service account with global scope. This enables consistent, platform-wide agent identities. **User Experience:** ``` User registers "Claude Assistant" flow → User reserves service account name to associate with flow → System creates @claude service account (instance-wide) → @claude becomes available in the catalog → Any user can then add a trigger in their project and use `@claude` in any context where they have access. ``` **Advantages:** 1. **Intuitive User Experience**: Global names like `@claude`, `@gemini`, or `@duodeveloper` feel natural and consistent across the platform 2. **Simplified Mental Model**: Users don't need to understand group/project boundaries for agent interaction 3. **Reduced Naming Conflicts**: Single namespace prevents duplicate agent names across different scopes 4. **Enhanced Discoverability**: Global agents are more easily found and shared across teams **Disadvantages:** 1. **Namespace Collision Risk**: Popular names like `@claude` could be claimed by any user, potentially causing confusion or impersonation issues 2. **Security Blast Radius**: If composite identity is compromised, the vulnerability could potentially affect all GitLab.com users, not just a specific group 3. **Name Squatting Concerns**: Users might register desirable names without active use, blocking legitimate use cases </details> <details> <summary> Option 2: Project-Scoped Service Accounts with Group Association </summary> **Implementation Approach:** Service accounts are created when flows are added to specific projects, with accounts scoped to the containing group. This creates a more contained, hierarchical approach to agent identity. **User Experience:** ``` User adds "Claude Assistant" flow to "MyProject" → User selects a name to give the flow → System creates @claude-myproject service account (group-scoped) → @claude-myproject available within the group's projects → Different groups can have their own @claude-[suffix] variants ``` **Advantages:** 1. **Enhanced Security Isolation**: Group-level boundaries limit the potential impact of security vulnerabilities 2. **Organizational Alignment**: Agent scope matches GitLab's existing permission and organizational model 3. **Reduced Global Namespace Pressure**: Multiple groups can use similar names with different suffixes 4. **Better Access Control**: Aligns with existing group-based permission systems **Disadvantages:** 1. **Decreased User Experience**: Users cannot use simple, memorable names like `@claude` across contexts 2. **Increased Complexity**: Users must understand and remember group-specific agent names 3. **Reduced Discoverability**: Agents are less visible outside their group context 4. **Naming Convention Overhead**: Requires establishing and maintaining consistent naming patterns ## Implementation Considerations ### Pre-Built Agent Integration For system-provided agents like `DuoDeveloper` that power standard workflows: **Auto-Provisioning Strategy:** 1. **Project Creation Hooks**: Automatically add standard flow triggers when projects are created 2. **Transparent Integration**: Pre-configured triggers appear in Flow Triggers settings but don't require user action 3. **User Control**: Allow users to disable or customize auto-provisioned triggers as needed 4. **Progressive Disclosure**: Surface advanced configuration options only when users need them **Example Standard Flows:** - Issue to MR Flow (automated merge request creation) - Software Development Flow (code creation and debugging) ### Permission Elevation Strategy Both options require addressing the current limitation where non-maintainer users cannot create service accounts: **Proposed Solutions:** 1. **Automatic Privilege Escalation**: Temporarily elevate user permissions for service account creation when creating a flow 2. **Admin-Level Pre-Approval**: Allow admins to pre-approve users for agent service account creation (only applicable if we use group level accounts) Proof of concept: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/209779 </details>