# 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
```