123 lines
3.1 KiB
Markdown
123 lines
3.1 KiB
Markdown
# Helpdesk Git Webhook Tracking
|
|
|
|
The Helpdesk module can ingest signed Git push webhooks and automatically link commits to tickets when commit messages, branch names, or commit URLs contain a ticket reference such as `HD-2026-00012`.
|
|
|
|
## 1. Register the repository
|
|
|
|
Open the Helpdesk settings page:
|
|
|
|
```text
|
|
/helpdesk/settings
|
|
```
|
|
|
|
In the **Git** section, create a repository with:
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Provider | `github`, `gitlab`, or `git` |
|
|
| Remote URL | Your repository remote URL |
|
|
| Default branch | Usually `develop` or `main` |
|
|
| Webhook secret | A strong random secret, for example `openssl rand -hex 32` |
|
|
|
|
After saving, the repository table shows the webhook endpoint:
|
|
|
|
```text
|
|
/api/helpdesk/git/webhook/{repository_id}
|
|
```
|
|
|
|
## 2. Ticket reference convention
|
|
|
|
Use the Helpdesk ticket reference in branch names and commit messages:
|
|
|
|
```bash
|
|
git checkout -b feature/HD-2026-00012-canned-responses
|
|
git commit -m "HD-2026-00012 Add canned response macro rendering"
|
|
```
|
|
|
|
The parser recognises this format:
|
|
|
|
```text
|
|
HD-YYYY-00000
|
|
```
|
|
|
|
The first matching reference is linked to the stored commit when the ticket exists and matches the repository company/project scope.
|
|
|
|
## 3. GitHub setup
|
|
|
|
In GitHub, open the repository settings and add a webhook:
|
|
|
|
| GitHub field | Value |
|
|
| --- | --- |
|
|
| Payload URL | `https://your-app.test/api/helpdesk/git/webhook/{repository_id}` |
|
|
| Content type | `application/json` |
|
|
| Secret | Same value stored in Helpdesk |
|
|
| Events | Push events |
|
|
|
|
The module validates `X-Hub-Signature-256` using HMAC SHA-256 and rejects unsigned or invalid requests.
|
|
|
|
## 4. GitLab setup
|
|
|
|
In GitLab, open **Settings > Webhooks** and add:
|
|
|
|
| GitLab field | Value |
|
|
| --- | --- |
|
|
| URL | `https://your-app.test/api/helpdesk/git/webhook/{repository_id}` |
|
|
| Secret token | Same value stored in Helpdesk |
|
|
| Trigger | Push events |
|
|
|
|
The module validates `X-Gitlab-Token` and rejects invalid requests.
|
|
|
|
## 5. Generic Git provider setup
|
|
|
|
For a simple internal provider, send a JSON push payload to the same endpoint with:
|
|
|
|
```http
|
|
X-Helpdesk-Token: your-secret
|
|
X-Helpdesk-Event: push
|
|
```
|
|
|
|
The payload should include:
|
|
|
|
```json
|
|
{
|
|
"ref": "refs/heads/develop",
|
|
"commits": [
|
|
{
|
|
"id": "full-commit-hash",
|
|
"message": "HD-2026-00012 Fix ticket workflow",
|
|
"url": "https://example.test/commit/full-commit-hash",
|
|
"timestamp": "2026-06-15T10:00:00+00:00",
|
|
"author": {
|
|
"name": "Support Agent",
|
|
"email": "agent@example.com"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 6. Audit trail
|
|
|
|
Every accepted, ignored, or rejected webhook delivery is recorded in:
|
|
|
|
```text
|
|
helpdesk_git_webhook_logs
|
|
```
|
|
|
|
Stored data includes provider, event, delivery id, status, message, commit count, linked count, ignored count, payload, and received timestamp.
|
|
|
|
## 7. Verification commands
|
|
|
|
Run the focused feature test after installing the updated module:
|
|
|
|
```bash
|
|
php artisan test Modules/Helpdesk/Tests/Feature/GitWebhookIngestionTest.php
|
|
```
|
|
|
|
Then run the full Helpdesk test set:
|
|
|
|
```bash
|
|
php artisan test Modules/Helpdesk/Tests/Feature Modules/Helpdesk/Tests/Unit
|
|
php artisan dusk Modules/Helpdesk/Tests/Browser
|
|
```
|