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

  5. Immediate permission challenges - Currently only @marin can enable agents/flows and is out of office until end of March, blocking progress

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

Proposal

Based on discussion with @amandarueda and learnings from the CI component contributor success model:

Location and Structure

Use the @components top-level group with a dedicated subgroup for agents and flows:

  • Create @components/agents-and-flows subgroup to organize all GitLab-maintained agents and flows
  • Each agent/flow gets a dedicated project within this subgroup
  • Leverage existing https://gitlab.com/components/ai-catalog infrastructure built by contributor success

Why this approach:

  1. Solves permission challenges: Uses the proven CI component model with built-in approval processes
  2. Separation of concerns: Dedicated projects allow independent CI, permissions, and configuration without juggling "other things" in the repo
  3. Leverages existing infrastructure: The @components group already has:
    • @gitlab-bot automations configured
    • Data consumption patterns for community contributions
    • Established workflows and tooling
  4. Built-in benefits: Diffs, audit trails, and approval processes come for free
  5. Consistency: Aligns with how CI/CD components are already organized

Project Structure

  • Dedicated project per agent/flow for:
    • Independent versioning and release cycles
    • Clear ownership boundaries
    • Simpler CI/CD pipelines
    • Easier forking and contribution

Next Steps

  1. Confirm approval from CI component maintainers to share the @components top-level group
  2. Create @components/agents-and-flows subgroup
  3. Document standards and create templates
  4. Begin migrating/creating agents and flows following this structure

Questions to Answer

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

Decision: @components/agents-and-flows subgroup ✅

Options considered:

  • 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)

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

Decision: Yes, dedicated project per agent/flow ✅

Benefits:

  • ✅ Independent versioning
  • ✅ Clear ownership
  • ✅ Simpler CI/CD
  • ✅ Easier to fork/contribute
  • ✅ Separate configuration and permissions

3. What naming conventions should we use?

To be documented based on @components group standards.

Examples to consider:

  • @components/agents-and-flows/code-review-agent
  • @components/agents-and-flows/ci-pipeline-fix-flow

4. How should ownership and permissions be structured?

Leverage the existing @components group model:

  • Use established approval processes from CI component workflow
  • Configure @gitlab-bot automations
  • Define maintainer roles per project

5. How should versioning and releases work?

To be documented based on CI component patterns:

  • Semantic versioning for each agent/flow
  • Independent release cycles per project
  • Version pinning in the catalog

Success Criteria

  • Clear documentation of where GitLab-maintained agents and flows should be created
  • Established project structure standards (dedicated 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
  • Approval from CI component maintainers to use @components group

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

Reference: CI component infrastructure at https://gitlab.com/components/ai-catalog

Edited by Lee Tickett