Add comprehensive GitLab webhook setup instructions for enterprise deployments

[jpshackelford]

Summary

This PR addresses the incomplete GitLab webhook documentation in the OpenHands Cloud Helm chart README. While the GitHub section includes comprehensive webhook setup instructions, the GitLab section was missing critical webhook configuration steps needed for enterprise deployments.

Problem

The current GitLab integration documentation only covers OAuth application setup but lacks webhook configuration instructions. This means:

• Users can authenticate with GitLab but can't use @openhands mentions in issues/MRs
• No guidance on how to enable automated GitLab issue/MR processing
• Missing webhook secret management in Kubernetes secrets
• No troubleshooting guidance for webhook-related issues

Changes Made

1. Enhanced GitLab Application Setup

• Added webhook secret generation: export GITLAB_WEBHOOK_SECRET=head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32
• Updated Kubernetes secret: Include webhook-secret in the gitlab-app secret
• Added webhook setup reference: Point users to the webhook setup section

2. Comprehensive Webhook Setup Section

Added a complete "Setting Up Webhooks for Issue and PR Integration" section with:

Option 1: Automated Webhook Installation

• Instructions for accessing the OpenHands pod
• Running the webhook installation script: python enterprise/sync/install_gitlab_webhooks.py
• CronJob configuration for ongoing webhook management
• Complete Kubernetes CronJob YAML example

Option 2: Manual Webhook Configuration

• Step-by-step GitLab UI instructions
• Complete webhook configuration parameters
• Event type selection guidance
• Testing and verification steps

3. Technical Documentation

• Webhook specifications: Name, description, URL pattern, content type, SSL settings
• Event types: Complete list of required GitLab webhook events
• URL format: https://{your-domain}/integration/gitlab/events

4. Troubleshooting Guide

• Common issues: Permission problems, authentication failures, webhook delivery issues
• Debugging steps: Database checks, log analysis, webhook testing
• Verification methods: How to confirm webhooks are working

Technical Analysis

The documentation is based on analysis of the OpenHands codebase:

• Webhook installer: enterprise/sync/install_gitlab_webhooks.py - Automated webhook installation script
• GitLab service: enterprise/integrations/gitlab/gitlab_service.py - Webhook installation logic
• Webhook endpoint: enterprise/server/routes/integration/gitlab.py - /integration/gitlab/events route
• Database model: enterprise/storage/gitlab_webhook.py - Webhook storage schema
• URL construction: enterprise/integrations/utils.py - GITLAB_WEBHOOK_URL constant

Webhook Installation Flow

1. Authentication: User authenticates with GitLab through OpenHands
2. Database preparation: System creates webhook entries in gitlab_webhook table
3. Manual installation: Admin runs webhook installer script or configures manually
4. Event processing: GitLab sends events to /integration/gitlab/events endpoint
5. Verification: System validates webhook secrets and processes events

Benefits

• Complete parity with GitHub webhook documentation
• Enterprise-ready instructions for production deployments
• Multiple options for different deployment scenarios
• Comprehensive troubleshooting for common issues
• Automation support via CronJob configuration

Testing

• Verified webhook configuration parameters match the codebase implementation
• Confirmed event types align with the webhook installer script
• Validated troubleshooting steps against common failure scenarios
• Tested Kubernetes secret and CronJob configurations

References

All documentation is based on analysis of the following OpenHands source files:

• enterprise/sync/install_gitlab_webhooks.py - Webhook installation automation
• enterprise/integrations/gitlab/gitlab_service.py - GitLab API integration
• enterprise/integrations/utils.py - Webhook URL configuration
• enterprise/storage/gitlab_webhook_store.py - Database operations
• enterprise/server/routes/integration/gitlab.py - Webhook event processing

This ensures all documented procedures are factually accurate and match the actual implementation.

@jpshackelford can click here to continue refining the PR

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Pull Request Checks

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #243 at branch `add-gitlab-webhook-setup-instructions`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}