major helpdesk updates

Modules/Helpdesk/Docs/GIT_WEBHOOK_TRACKING.md

@@ -0,0 +1,122 @@
+# 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
+```

Modules/Helpdesk/Docs/INSTALL.md

@@ -91,3 +91,9 @@ or directly:
 php artisan test Modules/Helpdesk/tests/Feature
 php artisan dusk Modules/Helpdesk/tests/Browser
 ```
+## 9. Git webhook tracking
+
+The module supports signed Git push webhooks for repository commit tracking. Register repositories in `/helpdesk/settings`, copy the generated webhook endpoint from the Git table, and configure GitHub/GitLab push webhooks with the same secret stored on the repository.
+
+See `Docs/GIT_WEBHOOK_TRACKING.md` for provider-specific setup, ticket reference conventions, and verification commands.
+