Webhook-based trigger for GitLab Duo Workflows from external systems (e.g., Jira)

Problem to solve

Teams using external issue tracking systems (like Jira) want to leverage GitLab's AI-powered development capabilities without duplicating work items in GitLab. Currently, there's no way to trigger a GitLab Duo Workflow from an external system webhook, forcing teams to either:

  1. Manually create issues in GitLab to trigger AI workflows
  2. Duplicate issues across both systems
  3. Maintain complex custom integration scripts

This prevents teams from using Jira as their single source of truth while still benefiting from GitLab's AI-assisted development capabilities.

Intended users

  • Priyanka (Platform Engineer) - Integrating external issue tracking systems with GitLab's AI capabilities
  • Delaney (Development Team Lead) - Managing development workflows across multiple tools with AI assistance
  • Devon (DevOps Engineer) - Automating feature development using AI workflows
  • Sasha (Software Developer) - Leveraging AI to develop features from external issue systems

User experience goal

Teams should be able to configure a webhook endpoint in GitLab that accepts payloads from external systems (like Jira) and triggers a GitLab Duo Workflow (similar to the developer flow triggered by issues). This enables a seamless workflow where:

  1. An issue is created/updated in Jira with feature requirements
  2. Jira sends a webhook to GitLab with issue details
  3. GitLab receives the webhook and triggers a Duo Workflow
  4. The AI workflow analyzes the requirements and develops the feature
  5. The workflow creates merge requests, commits code, and manages the development process
  6. Results are optionally synced back to Jira

Proposal

1. Webhook Endpoint for Workflow Triggers

Create a new API endpoint that accepts webhook payloads and triggers Duo Workflows:

POST /api/v4/projects/:id/workflows/trigger

2. Payload Structure

The endpoint should accept a flexible JSON payload with workflow context:

{
  "workflow_type": "developer",
  "title": "Feature title from external system",
  "description": "Detailed feature requirements",
  "external_reference": "JIRA-123",
  "external_url": "https://jira.example.com/browse/JIRA-123",
  "external_system": "jira",
  "context": {
    "acceptance_criteria": "...",
    "priority": "high",
    "assignee": "developer@example.com"
  }
}

3. Workflow Execution

  • Trigger the specified Duo Workflow (e.g., developer flow) with the external system's data
  • The workflow should have access to the external reference and context
  • Workflow can create branches, commits, MRs, and manage the development process
  • Support for custom workflow configurations per project

4. Configuration

  • Allow projects to configure which workflows are triggered by webhooks
  • Support custom branch naming patterns based on external references
  • Optional: Auto-link created MRs back to external issues
  • Optional: Sync workflow results/status back to external system

5. Security Considerations

  • Require authentication token for webhook validation
  • Validate webhook signatures (HMAC-SHA256)
  • Rate limiting to prevent abuse
  • Audit logging of all workflow-triggered actions
  • Permissions: Webhook must have appropriate permissions to trigger workflows
  • Workflows execute with configured service account permissions

6. Error Handling

  • Return meaningful error messages if workflow trigger fails
  • Support webhook retry mechanisms
  • Log failures for debugging
  • Notify external system of workflow status (optional)

Further details

Use Case: Jira to GitLab AI-Assisted Development

  1. Product team creates issue in Jira: "PROJ-123: Implement user authentication with OAuth2"
  2. Jira webhook sends payload to GitLab with feature requirements
  3. GitLab receives webhook and triggers Duo Developer Workflow with:
    • Feature title and requirements from Jira
    • Link to original Jira issue
    • Context about acceptance criteria
  4. AI workflow:
    • Analyzes requirements
    • Creates feature branch
    • Generates implementation code
    • Creates merge request with code changes
    • Optionally creates tests
  5. Developer reviews AI-generated code and MR
  6. Upon merge, workflow optionally updates Jira issue status

Alternative Use Cases

  • ServiceNow to GitLab AI development
  • Linear to GitLab AI development
  • Custom internal issue tracking systems
  • GitHub Issues to GitLab AI development (for teams migrating)
  • Slack commands triggering AI workflows with external context

Permissions and Security

  • Webhook endpoint requires authentication token (project-level or group-level)
  • HMAC-SHA256 signature validation for webhook authenticity
  • Audit trail of all webhook-triggered workflow executions
  • Rate limiting per webhook endpoint
  • Only users with Developer+ permissions can configure webhooks
  • Workflows execute with configured service account or bot permissions
  • External system data is treated as untrusted input and validated

Documentation

  • API documentation for the workflow trigger endpoint
  • Configuration guide for common systems (Jira, ServiceNow, Linear, etc.)
  • Security best practices for webhook configuration
  • Examples of webhook payload structures for different systems
  • Workflow configuration and customization guide
  • Troubleshooting guide for common issues

Testing

  • Unit tests for webhook payload validation
  • Integration tests for workflow triggering from various payload structures
  • Security tests for signature validation and rate limiting
  • End-to-end tests with mock external systems
  • Tests for workflow execution with external context

What does success look like, and how can we measure that?

Success would be measured by:

  1. Adoption: Number of projects using webhook-based workflow triggers
  2. Reliability: Workflow trigger success rate (target: >99%)
  3. Performance: Average time from webhook receipt to workflow execution (<2 seconds)
  4. User satisfaction: Positive feedback from teams using external issue trackers with AI workflows
  5. Integration ecosystem: Community contributions for additional system integrations
  6. Development velocity: Measurable improvement in feature development speed using AI workflows

Availability & Testing

  • Available on GitLab.com and Self-Managed instances
  • Should work with any external system that supports webhooks
  • Comprehensive testing with popular issue tracking systems (Jira, ServiceNow, Linear)
  • Integration with existing Duo Workflow capabilities

Links / references

Edited by Rob Jackson