Webhooks are a powerful way to automate your development workflow by triggering actions when specific events occur in your Gitea repository. In this guide, we'll walk through setting up a webhook receiver on Linux that responds to Gitea events.

Prerequisites

Before we begin, ensure you have:

• A Linux server with root access
• Gitea instance up and running
• Basic knowledge of bash scripting
• curl and jq installed for testing

Setting Up the Webhook Receiver

First, let's create a simple webhook receiver script that will listen for incoming HTTP POST requests from Gitea:

1#!/bin/bash
2
3# webhook.sh
4PORT=9000
5LOG_FILE="/var/log/webhook.log"
6
7# Create logging directory if it doesn't exist
8mkdir -p $(dirname $LOG_FILE)
9
10# Start a simple HTTP server using netcat
11while true; do
12    echo "Waiting for webhook requests on port $PORT..."
13    nc -l -p $PORT -c '
14        read request
15        echo "$(date): Received webhook request" >> '"$LOG_FILE"'
16        
17        # Read the headers
18        while read line && [ "$line" != $"\r" ]; do
19            echo "$line" >> '"$LOG_FILE"'
20        done
21        
22        # Read and process the body
23        length=$(cat | wc -c)
24        if [ $length -gt 0 ]; then
25            body=$(cat)
26            echo "$body" >> '"$LOG_FILE"'
27            
28            # Extract event type from headers
29            if echo "$request" | grep -q "X-Gitea-Event"; then
30                event=$(echo "$request" | grep "X-Gitea-Event" | cut -d" " -f2)
31                echo "Event Type: $event" >> '"$LOG_FILE"'
32            fi
33            
34            # Execute specific actions based on the event
35            case "$event" in
36                "push")
37                    # Handle push events
38                    /path/to/your/deploy-script.sh
39                    ;;
40                "pull_request")
41                    # Handle pull request events
42                    /path/to/your/pr-script.sh
43                    ;;
44            esac
45        fi
46        
47        # Send response back to Gitea
48        echo -e "HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n"
49    '
50done
51

Setting Up as a Systemd Service

To ensure our webhook receiver runs continuously and starts automatically with the system, we'll create a systemd service:

1# /etc/systemd/system/gitea-webhook.service
2[Unit]
3Description=Gitea Webhook Receiver
4After=network.target
5
6[Service]
7Type=simple
8User=webhook
9Group=webhook
10ExecStart=/usr/local/bin/webhook.sh
11Restart=always
12RestartSec=5
13
14[Install]
15WantedBy=multi-user.target
16

To install and start the service:

1# Create webhook user
2sudo useradd -r -s /bin/false webhook
3
4# Copy the script to the proper location
5sudo cp webhook.sh /usr/local/bin/
6sudo chmod +x /usr/local/bin/webhook.sh
7
8# Set up the service
9sudo systemctl daemon-reload
10sudo systemctl enable gitea-webhook
11sudo systemctl start gitea-webhook
12

Configuring Gitea Webhook

To set up the webhook in your Gitea repository:

1. Navigate to Settings > Webhooks > Add Webhook
2. Select "Gitea" as the webhook type
3. Configure the following settings:
   • Target URL: http://your-server-ip:9000
   • HTTP Method: POST
   • Content Type: application/json
   • Secret: (Optional but recommended for security)
   • Select the events that should trigger the webhook

Implementing Security Measures

For production environments, implement these security measures:

1#!/bin/bash
2
3# Add to webhook.sh
4SECRET="your-secret-here"
5
6# Verify signature
7signature=$(echo "$request" | grep "X-Gitea-Signature" | cut -d" " -f2)
8calculated=$(echo -n "$body" | openssl sha256 -hmac "$SECRET" | cut -d" " -f2)
9
10if [ "$signature" != "$calculated" ]; then
11    echo "Invalid signature" >> "$LOG_FILE"
12    exit 1
13fi
14

Testing Your Setup

Test your webhook implementation using curl:

1curl -X POST http://localhost:9000 \
2  -H "Content-Type: application/json" \
3  -H "X-Gitea-Event: push" \
4  -H "X-Gitea-Signature: your-signature" \
5  -d '{"ref":"refs/heads/main","repository":{"name":"test-repo"}}'
6

Monitoring and Troubleshooting

Keep track of your webhook's performance:

1# Check webhook logs
2tail -f /var/log/webhook.log
3
4# Check service status
5systemctl status gitea-webhook
6

Common Use Cases

Your webhook can automate various tasks:

• Automated Deployments: Trigger deployments when changes are pushed to specific branches
• Build Automation: Start CI/CD pipelines on push events
• Notification Systems: Send notifications to chat systems or email
• Documentation Updates: Rebuild documentation when changes are detected
• Backup Creation: Create repository backups on push events

Best Practices

To maintain a robust webhook system:

1. Always validate webhook signatures for security
2. Implement comprehensive error handling
3. Maintain detailed logging
4. Set up monitoring for the webhook service
5. Implement rate limiting to prevent abuse
6. Keep scripts modular and maintainable
7. Use appropriate timeout values
8. Implement retry mechanisms for failed actions

Conclusion

Gitea webhooks with Linux provide a powerful automation tool for your development workflow. By following this guide, you've learned how to set up a robust webhook receiver that can handle various Gitea events and trigger custom actions.

Remember to adapt the security measures and implementation details to your specific needs. Regular monitoring and maintenance will ensure reliable operation of your automated workflows.