feat(integrations): record deployments from GitLab and Flux webhooks

README.md

@@ -253,6 +253,7 @@ npm run dev
 - [📊 Events Guide](./docs/EVENTS.md) - Working with events
 - [📦 Catalog Guide](./docs/CATALOG.md) - Managing service catalog
 - [🔒 Locks Guide](./docs/LOCKS.md) - Distributed locking
+- [🔗 Deployment Integrations](./docs/INTEGRATIONS.md) - Record GitLab and Flux deployments automatically
 
 ### API Documentation
 - [🔌 API Specification](./docs/api-specification.md) - API reference

cmd/serv.go

@@ -23,6 +23,7 @@ import (
 	"github.com/bananaops/tracker/internal/auth"
 	"github.com/bananaops/tracker/internal/auth/identity"
 	"github.com/bananaops/tracker/internal/auth/sso"
+	"github.com/bananaops/tracker/internal/integrations"
 	store "github.com/bananaops/tracker/internal/stores"
 	"github.com/bananaops/tracker/server"
 	"github.com/go-openapi/runtime/middleware"
@@ -49,6 +50,18 @@ var serv = &cobra.Command{
 		if authCfg.AnonymousDefaulted {
 			slog.Warn("AUTH_ANONYMOUS_PERMISSIONS is not set: anonymous callers keep every permission except access:manage. This default becomes empty in the next major release.")
 		}
+
+		// Deployment integrations (GitLab and Flux webhooks). The routes are
+		// registered once the mux exists; an invalid configuration stops here.
+		integrationsCfg, err := integrations.LoadConfig(os.LookupEnv)
+		if err != nil {
+			log.Fatalf("invalid integrations configuration: %v", err)
+		}
+		for _, w := range integrationsCfg.Warnings {
+			slog.Warn(w)
+		}
+		slog.Info("deployment integrations", integrationsCfg.LogAttrs()...)
+
 		userStore := store.NewAuthUserStore()
 		teamStore := store.NewAuthTeamStore()
 		keyStore := store.NewAuthAPIKeyStore()
@@ -175,6 +188,14 @@ var serv = &cobra.Command{
 		// Register custom links CRUD endpoints
 		server.RegisterLinksHandler(mux)
 
+		// Register the GitLab and Flux deployment webhooks (configured sources only).
+		// NewIntegrationDeps opens collections, so it only runs when a source is set.
+		if integrationsCfg.Enabled() {
+			if err := server.RegisterIntegrationHandlers(mux, integrationsCfg, server.NewIntegrationDeps(events)); err != nil {
+				log.Fatalf("cannot register integration webhooks: %v", err)
+			}
+		}
+
 		// Setup Swagger documentation with go-swagger
 		opts := middleware.SwaggerUIOpts{SpecURL: "/swagger.json"}
 		sh := middleware.SwaggerUI(opts, nil)

docs/CONFIGURATION.md

@@ -99,6 +99,37 @@ AUTH_OIDC_CLIENT_SECRET=<from your secret store>
 # Redirect URI to register: https://tracker.example.com/api/v1alpha1/auth/oidc/callback
 ```
 
+### Deployment integrations
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INTEGRATION_GITLAB_SIGNING_TOKEN` | - | GitLab signing token, `whsec_<base64>`. When set, the `webhook-signature` header is required and `INTEGRATION_GITLAB_SECRET_TOKEN` is ignored. |
+| `INTEGRATION_GITLAB_SECRET_TOKEN` | - | Legacy GitLab secret token, compared against `X-Gitlab-Token`. Ignored when the signing token is set. |
+| `INTEGRATION_FLUX_HMAC_KEY` | - | HMAC key shared with the Flux `Provider` Secret (key `token`). Enables the Flux webhook endpoint. |
+| `INTEGRATION_WEBHOOK_TOLERANCE` | `5m` | Freshness window (Go duration) for GitLab's `webhook-timestamp` and Flux's event `timestamp`. |
+| `INTEGRATION_ENVIRONMENTS` | `production=production,staging=preproduction` | Comma separated `source=tracker` pairs mapping a GitLab or Flux environment name to a Tracker environment. Source keys are matched case-insensitively. |
+
+An invalid value stops Tracker at startup, with an error that never includes the secret itself:
+
+- `INTEGRATION_GITLAB_SIGNING_TOKEN` not prefixed with `whsec_`, or the part after the prefix is
+  not valid base64, or decodes to an empty value.
+- `INTEGRATION_GITLAB_SECRET_TOKEN` shorter than 16 characters.
+- `INTEGRATION_FLUX_HMAC_KEY` shorter than 32 bytes.
+- `INTEGRATION_WEBHOOK_TOLERANCE` not a positive Go duration (for example `5m`).
+- `INTEGRATION_ENVIRONMENTS` malformed (an entry without `=`, an empty key, or a duplicate key),
+  or a value that is not one of the Tracker environment names: `development`, `integration`,
+  `TNR`, `UAT`, `recette`, `preproduction`, `production`, `mco` (these are case-sensitive).
+
+See [INTEGRATIONS.md](INTEGRATIONS.md) for the GitLab and Flux setup this configures.
+
+**Example:**
+```bash
+INTEGRATION_GITLAB_SIGNING_TOKEN=whsec_<base64-value-from-secret-manager>
+INTEGRATION_FLUX_HMAC_KEY=<32-byte-value-from-secret-manager>
+INTEGRATION_WEBHOOK_TOLERANCE=5m
+INTEGRATION_ENVIRONMENTS=production=production,staging=preproduction
+```
+
 ### Slack Integration
 
 | Variable | Default | Description |

docs/EVENTS.md

@@ -60,7 +60,7 @@ Tracker supports five main event types:
 #### Optional Fields
 
 - **attributes.message** (string): Detailed description
-- **attributes.source** (string): Event origin (e.g., `github_actions`, `jenkins`, `manual`)
+- **attributes.source** (string): Event origin (e.g., `github_actions`, `jenkins`, `manual`, `gitlab`, `flux`)
 - **attributes.priority** (int): Priority level (1=P1/Critical, 5=P5/Low)
 - **attributes.status** (int): Current status (see Status Values below)
 - **attributes.environment** (int): Target environment (see Environment Values below)
@@ -387,6 +387,13 @@ curl -X POST http://localhost:8080/api/v1alpha1/event \
   }'
 ```
 
+### Automatic deployment events
+
+Tracker can create and update deployment events on its own from GitLab and Flux webhooks,
+without any call to the REST or gRPC API. Each deployment produces a single event, taken through
+its lifecycle as notifications arrive: `start`, then `success`, `failure`, `warning` or `close`.
+See [INTEGRATIONS.md](INTEGRATIONS.md) for setup, environment mapping and troubleshooting.
+
 ## Best Practices
 
 ### 1. Use Descriptive Titles