How to Create GitLab Duo Agent Configuration YAML from Architecture Models

This is one possible way to explore architecture-derived GitLab Duo configuration. It is an idea for connecting policy and design decisions to agent execution settings, not a claim that iSecureByDesign automatically configures GitLab projects.

GitLab Duo flows can be configured with a YAML file that defines the environment in which the agentic system executes. The file is placed at .gitlab/duo/agent-config.yml in the project repository.

The agent-config.yml file can define the container image, setup script, network policy and cache used when a GitLab Duo flow runs in CI/CD. It is different from AGENTS.md or a system prompt: those provide instructions and context, while agent-config.yml controls the execution environment around the agent.

The GitLab agent configuration reference lists the supported keys. The file is read from the project’s default branch, so changes should be reviewed and committed like other security-sensitive project configuration.

A policy-to-agent configuration workflow

An iSecureByDesign environment configured for GitLab output can help users:

1. Model the system and its trust boundaries.

2. Add specification blocks for architecture, security, testing and delivery policy.

3. Select the controls that apply to the components being changed.

4. Generate the requirements specification.

5. Use a GitLab-specific output prompt to produce agent-config.yml values and comments.

6. Review the generated configuration and commit it to .gitlab/duo/agent-config.yml.

For example, architecture and policy decisions may determine which domains a flow is allowed to access, which setup commands are required, and whether a custom image is needed. The generated YAML should express those decisions using GitLab’s supported configuration keys.

Example agent-config.yml

A simple configuration might look like this:

image: python:3.11

setup_script:
  - pip install -r requirements.txt

network_policy:
  include_recommended_allowed: true
  allowed_domains:
    - api.example.com
  denied_domains:
    - unapproved.example.com

cache:
  paths:
    - .cache/pip

In an iSecureByDesign workflow, the allowed integration, isolation and implementation requirements can originate in the diagram and policy controls. The output prompt then formats the selected guidance as GitLab-compatible YAML. The exact keys and values must remain within GitLab’s supported schema.

GitLab notes that setup_script runs before the main flow and has access to the flow environment, so it should be reviewed carefully. Do not use it to bypass the intended network or security boundaries. See the GitLab flow execution guidance for the execution model and security considerations.

Keep agent configuration separate from agent instructions

agent-config.yml defines how the flow executes. It does not replace the instructions that define what the agent should do. GitLab projects may also use AGENTS.md, custom rules, skills and merge-request review instructions for project context and agent behavior. The GitLab customization documentation explains how these methods work together.

The policy output should explain which component or boundary each rule applies to, what implementation behavior is required, and what evidence should be produced. The YAML then expresses the execution settings that support those requirements.

For example:

When modifying the customer API, preserve the existing authorization middleware. Do not allow direct browser access to the database. Validate external input at the API boundary and add tests for authorized, denied and invalid requests.

That guidance can be derived from the diagram and controls, then used in the appropriate GitLab artifact. The GitLab AGENTS.md documentation explains the separate project and subdirectory instruction mechanism.

iSecureByDesign users can prototype this workflow by extending a diagram environment with GitLab-specific specification blocks and an output prompt. The generated specification remains the architecture-linked source, while agent-config.yml is the delivery format for the flow execution environment.

This connects AI Coding Tool Policy Management to a concrete repository workflow without requiring every agent to receive every organisational policy.

Related Reading

• AI Coding Rules vs Steering Files vs Repository Instructions
• Secure-by-Design Requirements for AI-Generated Code
• Outputs stage help

About Agentic Thoughts: This Agentic Thought was generated with AI. Agentic Thoughts are part of an ongoing process of evolving ideas about iSecureByDesign and how it may be applied to real-world problems. They are exploratory and do not necessarily represent a final product commitment, implementation, or formal advice.