# webhook-server

**Repository Path**: duxvfeng/webhook-server

## Basic Information

- **Project Name**: webhook-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Webhook Server

[中文版](README.zh-CN.md)

A GitLab Push Webhook service based on Spring Boot, designed to receive code push events, trigger notifications, and automatically generate/update daily report descriptions in Zentao weekly task.

## Features

- **Receive GitLab Push Webhook**
  - Validate `X-Gitlab-Token` secret key
  - Filter by branch whitelist (default allows `main`, `master`, `release/*`)
  - Parse commit messages and persist to local H2 database

- **Notification Distribution**
  - DingTalk bot Markdown notifications (optional)
  - Zentao `api-webhook` notifications (optional)

- **Weekly & Daily Report Automation**
  - Scheduled creation of Zentao weekly tasks for each mapped user
  - Scheduled aggregation of Push events within the week into daily report descriptions, appended to corresponding weekly tasks
  - Support parsing working hours from commit messages, automatically summarizing daily hours
  - Commit message polishing: Batch process commit messages via Claude API to generate cleaner daily report descriptions

- **Admin Panel**
  - Web management interface based on Spring Security + Thymeleaf
  - Maintain mapping relationships between GitLab usernames and Zentao usernames
  - Path: `/admin`

## Tech Stack

| Technology | Version/Description |
|------------|---------------------|
| Java | 17 |
| Spring Boot | 3.2.5 |
| Spring Security | Form login + Role control |
| Thymeleaf | Admin panel pages |
| MyBatis | Data persistence layer |
| H2 | Local file database (`./data/webhook-server`) |
| Maven | Build tool |
| Docker | Container deployment (optional) |

## Project Structure

```text
src/main/java/com/example/webhookserver/
├── WebhookServerApplication.java      # Startup class
├── config/                             # Configuration classes and properties
├── controller/                         # Webhook API
├── filter/                              # Secret Token / branch filtering
├── model/                               # PushEvent, CommitInfo models
├── notifier/                           # DingTalk, Zentao notifiers
├── parser/                              # GitLab Payload parser
├── service/                             # Core business logic
├── storage/                             # PushEvent storage & HTML generation
├── report/                              # Daily/weekly report description generation
├── weekly/                              # Weekly task scheduling & Zentao integration
├── admin/                               # Admin panel
├── zentao/                              # Zentao Token / task client
└── polish/                              # Claude API commit message polishing
```

## Quick Start

### 1. Requirements

- JDK 17+
- Maven 3.8+
- (Optional) Docker 20.10+

### 2. Local Run

```bash
# Clone project
git clone <repository-url>
cd webhook-server

# Build and test
./mvnw test

# Start application (default port 15200)
./mvnw spring-boot:run

# Or build and run
./mvnw package
java -jar target/webhook-server-0.0.1-SNAPSHOT.jar
```

### 3. Configuration

Create `.env` file in project root, configure required environment variables:

```bash
# Required: GitLab Webhook secret key
GITLAB_SECRET_TOKEN=your-gitlab-secret-token

# Optional: DingTalk notification
DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxx
DINGTALK_SECRET=SECxxx

# Optional: Zentao integration
ZENTAO_BASE_URL=http://your-zentao-host:port/
ZENTAO_USERNAME=your-username
ZENTAO_PASSWORD=your-password

# Optional: Weekly report
WEEKLY_REPORT_ENABLED=true
WEEKLY_REPORT_PROJECT_ID=2
WEEKLY_REPORT_EXECUTION_ID=3
WEEKLY_REPORT_ASSIGNED_TO=dxf

# Optional: Commit message polishing
REPORT_POLISHING_ENABLED=true
ANTHROPIC_AUTH_TOKEN=your-anthropic-token
CLAUDE_BASE_URL=http://your-claude-proxy:port/
CLAUDE_MODEL=your-model
```

### 4. Access Admin Panel

Open browser and navigate to:
```
http://localhost:15200/admin
```

Default admin credentials (change in `.env`):
- Username: `admin`
- Password: set via `ADMIN_PASSWORD` environment variable

## Webhook Configuration

### GitLab Webhook Setup

1. Navigate to your GitLab project: **Settings → Webhooks**
2. Add new webhook with URL: `http://your-server:15200/api/v1/webhooks/gitlab`
3. Secret token: same value as `GITLAB_SECRET_TOKEN`
4. Trigger events: **Push events**
5. Enable **SSL verification** (if using HTTPS)

## Development

### Build Project

```bash
# Compile
./mvnw compile

# Run tests
./mvnw test

# Package
./mvnw package
```

### Code Quality

```bash
# Check code style
./mvnw checkstyle:check

# Run PMD checks
./mvnw pmd:check

# Run all quality gates
./mvnw clean verify
```

## Deployment

### Docker Deployment

```bash
# Build image
docker build -t webhook-server .

# Run container
docker run -d \
  --name webhook-server \
  -p 15200:15200 \
  -v $(pwd)/data:/app/data \
  -e GITLAB_SECRET_TOKEN=your-secret-token \
  webhook-server
```

See [DOCKER.md](DOCKER.md) for detailed deployment guide.

## Configuration Reference

### Application Properties

Main configuration file: `src/main/resources/application.yml`

Key configurations:
- Server port: `15200`
- H2 database: `./data/webhook-server`
- Branch whitelist: `main`, `master`, `release/*`

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GITLAB_SECRET_TOKEN` | ✅ | GitLab Webhook secret token |
| `ZENTAO_BASE_URL` | ❌ | Zentao server URL |
| `ZENTAO_USERNAME` | ❌ | Zentao username |
| `ZENTAO_PASSWORD` | ❌ | Zentao password |
| `ANTHROPIC_AUTH_TOKEN` | ❌ | Anthropic API key for polishing |
| `ADMIN_PASSWORD` | ❌ | Admin panel password |

## Troubleshooting

### Application fails to start

Check if required environment variables are set:
```bash
# Linux/Mac
echo $GITLAB_SECRET_TOKEN

# Windows
echo %GITLAB_SECRET_TOKEN%
```

### Webhook returns 401

- Verify `GITLAB_SECRET_TOKEN` matches GitLab webhook configuration
- Check application logs for authentication errors

### Database errors

- Check H2 database file permissions: `./data/webhook-server.mv.db`
- Ensure disk has sufficient space

## License

[Specify your license here]

## Contributing

[Specify your contribution guidelines here]

## Support

For issues and questions, please contact the development team.