Best practices for organizing GitLab-maintained agents and flows

Problem Statement

We are actively building GitLab-maintained agents and flows for the Duo Agent Platform, but we lack documented standards for where these should live and how they should be organized. This creates several immediate problems:

Why this matters now:

  1. Teams are blocked or making inconsistent decisions - Without clear guidance, different teams may choose different organizational structures, leading to:

    • Inconsistent user experience when discovering/using GitLab-maintained content
    • Difficulty maintaining and updating agents/flows across different locations
    • Confusion for contributors about where to submit improvements

  2. We risk technical debt - If we build agents/flows without a clear structure now, we'll face costly refactoring later when we need to:

    • Migrate projects to a standardized location
    • Restructure repositories and update all references
    • Fix broken dependencies and catalog links

  3. Community contribution is unclear - Without documented standards, potential contributors don't know:

    • Where to find the source code for GitLab-maintained agents/flows
    • How to fork or contribute improvements
    • What the approval and ownership process looks like

  4. Scalability concerns - As we add more agents and flows, an ad-hoc approach will become unmaintainable:

    • No clear ownership model
    • Inconsistent versioning and release processes
    • Difficulty tracking what's officially maintained vs. experimental

What we need to decide:

We need to establish and document clear standards before we scale up agent/flow creation, covering:

  • Location: Which GitLab group(s)/project(s) should host GitLab-maintained agents and flows?
  • Project structure: Should each agent/flow have a dedicated project, or can multiple agents/flows live in the same project?
  • Naming conventions: How should projects/groups be named?
  • Ownership and permissions: Who maintains these projects and what access controls should be in place?
  • Versioning and releases: How should GitLab-maintained agents/flows be versioned and released?

Background

The AI Catalog (https://gitlab.com/explore/) is established as the centralized place for all GitLab catalogues, including the Agents and Workflow Catalogue. However, the underlying project structure and organization standards for GitLab-maintained content are not clearly documented.

Related context:

  • #554595 mentions the AI Catalog as the north star location for discovery
  • Navigation discussions in #550186 (closed) and #550927 (closed) address UI placement but not underlying structure
  • Documentation shows the catalog as a discovery mechanism but doesn't specify source project organization

Questions to Answer

1. Where should GitLab-maintained agents and flows live?

Options to consider:

  • A single gitlab-org/duo-agents project containing all agents
  • A single gitlab-org/duo-flows project containing all flows
  • A gitlab-org/duo-catalog group with separate projects per agent/flow
  • Distributed across relevant stage groups (e.g., security agents in gitlab-org/secure)
  • Similar options but within components top level group (alongside CI/CD components)
  • Other structure?

Considerations:

  • Discoverability for contributors
  • Ownership and maintenance responsibilities
  • CI/CD pipeline complexity
  • Release cadence flexibility
  • Separation of concerns

2. Should each agent/flow have a dedicated project?

Dedicated project per agent/flow:

  • ✅ Pros: Independent versioning, clear ownership, simpler CI/CD, easier to fork/contribute
  • ❌ Cons: More projects to manage, potential duplication of tooling/templates

Multiple agents/flows in one project:

  • ✅ Pros: Centralized management, shared tooling, easier to maintain standards
  • ❌ Cons: Coupled release cycles, harder to assign ownership, more complex CI/CD

Hybrid approach:

  • Group related agents/flows together (e.g., by stage, by complexity, by team)

3. What naming conventions should we use?

Examples to consider:

  • gitlab-org/duo-agents/code-review-agent
  • gitlab-org/duo-catalog/agents/code-review
  • gitlab-org/secure/security-scan-agent
  • gitlab-org/duo-flows/ci-pipeline-fix

4. How should ownership and permissions be structured?

  • Should all GitLab-maintained agents/flows be owned by a central team?
  • Should stage groups own agents/flows relevant to their domain?
  • What permission levels should community contributors have?
  • How do we handle security and compliance for agents that access sensitive data?

5. How should versioning and releases work?

  • Semantic versioning for each agent/flow?
  • Coordinated releases across multiple agents/flows?
  • How do users pin to specific versions in the catalog?
  • How do we handle breaking changes?

Proposal

To be filled in based on discussion

Success Criteria

  • Clear documentation of where GitLab-maintained agents and flows should be created
  • Established project structure standards (dedicated vs. shared projects)
  • Naming convention guidelines documented
  • Ownership and permission model defined
  • Versioning and release strategy documented
  • Template projects or examples created for teams to follow
  • Migration plan for any existing agents/flows that don't follow the standards

Related Issues/Epics

Additional Context

This decision will impact:

  • Internal teams building GitLab-maintained agents and flows
  • Community contributors who want to contribute to or fork GitLab-maintained content
  • Users who consume these agents/flows from the AI Catalog
  • The overall maintainability and scalability of the Agent Platform ecosystem

Next Steps

  1. Gather input from relevant stakeholders (Workflow Catalog team, AI Framework team, stage groups)
  2. Review how similar features are organized (e.g., CI/CD Components, CI/CD templates)
  3. Document decision and create templates/examples
  4. Communicate standards to all teams building agents/flows
Edited by Lee Tickett