triggers
GitLab Duo Agent Platform - Triggers
Overview
Triggers are the mechanism that determines when a flow or agent action should execute. They act as the "event listener" layer of the GitLab Duo Agent Platform, connecting user intent (mentions, assignments) to automated agent workflows.
Introduced: GitLab 18.3 Status: Enabled by default Purpose: Automate flow execution based on GitLab events
Core Concepts
What is a Trigger?
A trigger defines:
- When a flow should run (event type)
- Who executes the flow (service account)
- What conditions must be met (optional filters)
- Where the flow runs (project, group)
Trigger Lifecycle
1. Event Occurs
(User mentions @ai-agent in MR comment)
†
2. Trigger Detection
(Platform detects mention event)
†
3. Condition Evaluation
(Check if conditions are met)
†
4. Service Account Validation
(Verify permissions)
†
5. Flow Execution
(Start associated flow)
†
6. Session Tracking
(Log execution and results)
Trigger Event Types
1. Mention Trigger
Activates when a service account is mentioned in a comment.
Use Cases:
- On-demand code reviews
- Security scans requested by developers
- Documentation generation
- Compliance checks
Syntax:
@service-account-name
Example:
# In issue or MR comment: "Can @ai-code-review please analyze this change?" # Triggers: trigger: event: mention service_account: ai-code-review-platform context: merge_request
Flow Definition:
name: on-demand-code-review description: Perform code review when mentioned in MR trigger: event: mention service_account: ai-code-review-platform conditions: - context: merge_request - state: opened - not_draft: true flow: agents: - code_review_agent steps: - name: analyze_changes agent: code_review_agent action: perform_review - name: post_findings agent: code_review_agent action: post_review_comments
Service Account Creation:
# Service account automatically created when flow is published: # @ai-code-review-platform # Naming convention: # ai-<flow-name>-<group-name>
2. Assign Trigger
Activates when a service account is assigned to an issue or merge request.
Use Cases:
- Automated triage
- Issue classification
- Priority assessment
- Workload balancing
Example:
name: automated-issue-triage description: Triage and classify new issues trigger: event: assign service_account: ai-triager-platform conditions: - context: issue - labels_empty: true # Only untriaged issues flow: agents: - planning_agent steps: - name: analyze_issue agent: planning_agent action: classify_issue - name: estimate_effort agent: planning_agent action: estimate_complexity - name: apply_labels agent: planning_agent action: update_labels - name: assign_milestone agent: planning_agent action: set_milestone - name: unassign_self agent: planning_agent action: remove_assignment
Usage:
1. Developer creates issue
2. Developer assigns @ai-triager-platform
3. Flow executes automatically
4. Issue is labeled and prioritized
5. Service account unassigns itself
3. Assign Reviewer Trigger
Activates when a service account is assigned as a reviewer to a merge request.
Use Cases:
- Mandatory code reviews before human review
- Security validation gates
- Compliance checks
- Style enforcement
Example:
name: mandatory-security-review description: Security review before human approval trigger: event: assign_reviewer service_account: ai-security-reviewer-platform conditions: - context: merge_request - target_branch: main - contains_security_files: true # Custom condition flow: agents: - security_analyst_agent steps: - name: scan_for_vulnerabilities agent: security_analyst_agent action: security_scan - name: check_secrets agent: security_analyst_agent action: secret_detection - name: assess_risk agent: security_analyst_agent action: risk_assessment - name: approve_or_block agent: security_analyst_agent action: conditional_approval conditions: - no_high_risk: true - no_secrets_found: true
Approval Workflow:
1. Developer creates MR to main
2. GitLab automatically assigns @ai-security-reviewer-platform
3. Security flow runs
4. If pass: Agent approves, human reviewers can proceed
5. If fail: Agent blocks, MR cannot merge until fixed
Trigger Configuration
Basic Trigger
trigger: event: mention | assign | assign_reviewer service_account: <account-name>
Trigger with Conditions
trigger: event: mention service_account: ai-code-review-platform conditions: # Context conditions - context: merge_request | issue | epic # State conditions - state: opened | merged | closed - draft: false # Label conditions - has_label: security - missing_label: reviewed # Branch conditions (MRs only) - source_branch_pattern: feature/* - target_branch: main | development # File conditions - file_patterns: - "src/**/*.ts" - "!**/*.test.ts" # Author conditions - author_not_bot: true - author_in_group: developers # Time conditions - business_hours: true - weekday_only: true
Multi-Condition Trigger
trigger: event: assign_reviewer service_account: ai-compliance-checker-platform conditions: all: # All conditions must be true (AND) - context: merge_request - target_branch: main any: # At least one must be true (OR) - has_label: compliance-required - file_patterns: ["**/api/**", "**/database/**"] none: # None can be true (NOT) - has_label: compliance-exempt - author: automation-bot
Service Accounts
Automatic Creation
Service accounts are automatically created when flows are published:
# When you publish this flow: name: security-scan # ... # GitLab creates: # @ai-security-scan-<group-name>
Naming Convention:
ai-<flow-name>-<group-name>
Examples:
- @ai-code-review-platform
- @ai-security-scan-engineering
- @ai-dependency-update-frontend
Manual Service Account Creation
For external agents or custom integrations:
# Create service account via API curl --request POST \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "username": "ai-custom-agent", "name": "Custom AI Agent", "email": "ai-custom-agent@gitlab.local", "service_account": true }' \ "https://gitlab.com/api/v4/groups/:group_id/service_accounts"
Service Account Permissions
Default Permissions: Developer role
Capabilities:
Read code and issues
Post comments
Create/update labels
Update MR status
Approve MRs (if assigned as reviewer)
Merge MRs (requires human approval)
Modify project settings
Manage group membership
Composite Identity Model
Effective Permissions = Human User © Service Account
Example:
- Human User: Maintainer role
- Service Account: Developer role
- Agent Action: Effective = Developer role
Security:
- Agent cannot escalate beyond user's permissions
- All actions attributed to both identities
- Audit trail maintained for compliance
Advanced Trigger Patterns
Cascading Triggers
Multiple flows triggered in sequence:
# Flow 1: Initial security scan name: security-scan-initial trigger: event: mention service_account: ai-security-scan-initial flow: steps: - name: quick_scan agent: security_analyst_agent action: fast_scan - name: trigger_deep_scan agent: security_analyst_agent action: mention_agent params: agent: "@ai-security-scan-deep" condition: - issues_found: true --- # Flow 2: Deep security analysis name: security-scan-deep trigger: event: mention service_account: ai-security-scan-deep flow: steps: - name: comprehensive_scan agent: security_analyst_agent action: deep_analysis - name: generate_report agent: security_analyst_agent action: create_security_report
Conditional Trigger Chains
name: smart-review-orchestrator trigger: event: assign_reviewer service_account: ai-review-orchestrator flow: steps: - name: determine_review_type agent: planning_agent action: classify_changes - name: trigger_security_review agent: planning_agent action: assign_reviewer params: reviewer: "@ai-security-reviewer" condition: - classification: security_related - name: trigger_performance_review agent: planning_agent action: assign_reviewer params: reviewer: "@ai-performance-reviewer" condition: - classification: performance_critical - name: trigger_standard_review agent: planning_agent action: assign_reviewer params: reviewer: "@ai-code-reviewer" condition: - classification: standard
Time-Based Triggers
name: nightly-dependency-check trigger: event: schedule service_account: ai-dependency-checker schedule: cron: "0 2 * * *" # 2 AM daily timezone: UTC conditions: - branch: main - not_already_running: true flow: agents: - security_analyst_agent steps: - name: check_dependencies agent: security_analyst_agent action: scan_dependencies - name: create_issue_if_needed agent: security_analyst_agent action: create_vulnerability_issue condition: - vulnerabilities_found: true
Event-Based Triggers (CI/CD Integration)
name: pipeline-failure-diagnostics trigger: event: pipeline_failed service_account: ai-pipeline-doctor conditions: - branch_pattern: "main|development|release/*" - failure_type: test_failure | build_failure - retry_count: >= 1 # Only after first retry flow: agents: - code_review_agent steps: - name: analyze_failure agent: code_review_agent action: diagnose_pipeline_failure - name: suggest_fixes agent: code_review_agent action: generate_fix_suggestions - name: create_incident agent: code_review_agent action: create_incident_issue condition: - severity: high
Trigger Management
View Active Triggers
# List all triggers in a project glab api projects/:project_id/duo/triggers # List triggers by service account glab api projects/:project_id/duo/triggers?service_account=ai-code-review
Enable/Disable Triggers
# In flow definition trigger: event: mention service_account: ai-code-review-platform enabled: true # or false to disable
# Via API curl --request PATCH \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ --data "enabled=false" \ "https://gitlab.com/api/v4/projects/:project_id/duo/triggers/:trigger_id"
Trigger History
# View trigger execution history glab api projects/:project_id/duo/triggers/:trigger_id/executions # Filter by date range glab api projects/:project_id/duo/triggers/:trigger_id/executions?since=2026-01-01
Trigger Security
Permission Checks
Before trigger executes:
1. Verify user has permission to trigger flow
2. Verify service account has permission to perform actions
3. Verify project/group settings allow agent platform
4. Verify flow is enabled and not blocked
5. Verify rate limits not exceeded
Rate Limiting
trigger: event: mention service_account: ai-code-review-platform rate_limits: per_user: 10/hour # Max 10 mentions per user per hour per_project: 50/hour # Max 50 executions per project per hour per_flow: 100/day # Max 100 total executions per day cooldown: same_context: 5m # Wait 5 min before re-triggering same MR/issue
Abuse Prevention
trigger: event: mention service_account: ai-code-review-platform abuse_prevention: require_context: true # Must be in issue/MR, not general comment require_permission: developer # Minimum role to trigger block_list: # Users who cannot trigger - spam-user-123 allowed_projects_only: true # Only in projects where flow is enabled
Audit Logging
All trigger executions are logged:
{ "trigger_id": "trig-abc123", "event": "mention", "service_account": "ai-code-review-platform", "triggered_by": { "user_id": 12345, "username": "john.doe", "role": "developer" }, "context": { "type": "merge_request", "project_id": 67890, "iid": 42 }, "timestamp": "2026-01-08T10:00:00Z", "session_id": "session-xyz789", "result": "success", "duration_seconds": 45, "conditions_evaluated": { "context": true, "state": true, "labels": true } }
Troubleshooting
Trigger Not Firing
Check:
- Is the trigger enabled?
- Do conditions match?
- Does user have permission?
- Is service account active?
- Are rate limits exceeded?
Debug:
# Check trigger configuration glab api projects/:project_id/duo/triggers/:trigger_id # Check recent executions glab api projects/:project_id/duo/triggers/:trigger_id/executions?limit=10 # Check service account status glab api users?username=ai-code-review-platform # View audit logs glab api projects/:project_id/audit_events?entity_type=duo_trigger
Trigger Firing Unexpectedly
Check:
- Review conditions - are they too broad?
- Check for cascading triggers
- Verify no automation loops
- Review recent trigger changes
Prevention:
trigger: event: mention service_account: ai-code-review conditions: # Add more specific conditions - context: merge_request - state: opened - not_draft: true - author_not_bot: true # Prevent bot loops safeguards: max_executions_per_context: 1 # Only run once per MR require_manual_retrigger: true # Require new mention to retry
Performance Issues
Optimize:
trigger: event: mention service_account: ai-code-review performance: # Cache context for repeated triggers cache_context: true cache_ttl: 5m # Debounce rapid triggers debounce: 30s # Wait 30s after first trigger # Queue vs immediate execution execution_mode: queued # or immediate # Priority for queue priority: normal # or high, low
Best Practices
1. Use Specific Conditions
Too Broad:
trigger: event: mention service_account: ai-code-review
Specific:
trigger: event: mention service_account: ai-code-review conditions: - context: merge_request - state: opened - target_branch: main - file_patterns: ["src/**/*.ts"] - not_draft: true
2. Implement Rate Limiting
trigger: event: mention service_account: ai-expensive-operation rate_limits: per_user: 5/day per_project: 20/day cooldown: same_context: 1h
3. Add Safety Guards
trigger: event: assign_reviewer service_account: ai-auto-approver conditions: - context: merge_request - all_tests_passed: true - security_scan_passed: true - no_high_severity_issues: true safeguards: require_human_approval: true # Agent approval not sufficient require_two_approvals: true # Agent + 1 human block_direct_merge: true # Prevent immediate merge
4. Provide Clear Documentation
name: automated-code-review description: | Performs automated code review when mentioned in an MR. Usage: @ai-code-review in any MR comment Scope: TypeScript files in src/ Checks: Style, complexity, test coverage Response time: ~30 seconds trigger: event: mention service_account: ai-code-review-platform # ...
5. Monitor and Alert
trigger: event: mention service_account: ai-critical-check monitoring: alert_on_failure: true alert_channels: - slack: "#agent-platform-alerts" - email: "devops@company.com" slo: success_rate: 0.95 # Alert if < 95% success p95_duration: 60s # Alert if p95 > 60s
Examples
Complete Example: Multi-Stage Security Flow
name: comprehensive-security-review description: Multi-stage security review with escalation trigger: event: assign_reviewer service_account: ai-security-comprehensive conditions: - context: merge_request - target_branch: main - any: - has_label: security - file_patterns: ["**/auth/**", "**/api/**"] flow: agents: - security_analyst_agent - code_review_agent steps: # Stage 1: Quick scan - name: quick_security_scan agent: security_analyst_agent action: fast_scan timeout: 30s # Stage 2: Detailed analysis if issues found - name: detailed_analysis agent: security_analyst_agent action: comprehensive_scan timeout: 5m condition: - quick_scan_issues_found: true # Stage 3: Code review for security patterns - name: security_code_review agent: code_review_agent action: security_focused_review timeout: 2m # Stage 4: Risk assessment - name: risk_assessment agent: security_analyst_agent action: assess_risk timeout: 1m # Stage 5: Decision - name: approve_or_block agent: security_analyst_agent action: security_decision params: auto_approve_threshold: low block_threshold: high require_human_review_threshold: medium # Stage 6: Notification - name: notify_security_team agent: security_analyst_agent action: send_notification params: channel: "#security-reviews" condition: - risk_level: high | critical monitoring: alert_on_failure: true alert_on_block: true track_metrics: true
Next Steps
- Master Flows: Read flows.md for flow orchestration
- Understand Agents: Review agents.md for agent management
- CI/CD Integration: Check integration.md for pipeline patterns
- Best Practices: Study best-practices.md for production
Last Updated: January 2026 GitLab Version: 18.7 (Beta), 18.8 GA (Upcoming)