How do audit events and audit event streaming work in GitLab, and how do you use them for compliance and security monitoring?

Think of audit events like the security camera system in a corporate office. Every door opening (authentication event), every file access (repository action), every safe combination change (permission modification) is recorded on video (audit log). Audit event streaming is like connecting that camera system to a central monitoring station (SIEM) across town, where security guards (security team) watch all feeds from all buildings (GitLab instances) in real time and sound alarms (alerts) when they spot suspicious activity.

GitLab audit events capture a wide range of actions across the platform. At the user level: login attempts (successful and failed), two-factor authentication changes, personal access token creation and revocation, and SSH key additions. At the group level: member additions and removals, role changes, group setting modifications, and SAML/SCIM provisioning events. At the project level: merge request approvals and merges, protected branch changes, CI/CD variable modifications, deploy token creation, repository visibility changes, and Runner registration. Each event records the timestamp, the actor (who performed the action), the target (what was affected), the action type, and additional metadata like IP address and user agent. Audit events are available in the GitLab UI at the instance, group, and project levels, and via the GraphQL API for programmatic access.

Internally, GitLab generates audit events through an event tracking system embedded in the Rails application. When a controller or service object performs an auditable action, it calls the audit event service, which creates an AuditEvent record in the database with the relevant metadata. For streaming, GitLab maintains a list of streaming destinations configured at the group or instance level. When an audit event is created, GitLab serializes it to JSON and sends an HTTP POST request to each configured streaming destination. The payload includes the event type, the full event details, and a verification header (X-Gitlab-Event-Streaming-Token) that the destination can use to validate the request authenticity. Streaming is asynchronous to avoid slowing down user-facing operations: events are queued in Sidekiq (GitLab's background job processor) and delivered with automatic retries on failure. GitLab supports streaming to generic HTTPS endpoints, AWS S3 buckets, and Google Cloud Logging as native destinations.

In production, a financial services company subject to SOX and PCI-DSS compliance would configure audit event streaming to their Splunk SIEM. The security team creates streaming destinations at the top-level group, ensuring all subgroups and projects inherit the configuration. Events flow to Splunk in real-time, where the security team builds dashboards and alerts: a dashboard showing all permission escalations in the last 24 hours, an alert for any CI/CD variable marked as protected being modified, an alert for any user receiving Owner role on a production project, and a report of all merge request approvals on projects tagged with the PCI-DSS compliance framework. For incident response, the security team uses the audit event GraphQL API to query specific timeframes and actors, answering questions like 'what did user john.doe do between 2AM and 4AM on March 15th?' The audit event data feeds into their quarterly compliance reports, demonstrating to auditors that all code changes to payment-processing systems were reviewed, approved, and deployed through the approved pipeline.

A critical gotcha is that audit event retention in GitLab's database is configurable by instance administrators, and events may be purged after a retention period (or may not, depending on the configuration). For compliance, always stream events to an external system with its own retention policy that meets regulatory requirements (typically 7 years for SOX, 1 year for PCI-DSS). Another common issue is the volume of events: a large GitLab instance can generate thousands of events per hour, and streaming destinations must be able to handle the throughput. Configure rate limiting and batching on the receiving end. Also, not all actions generate audit events; GitLab continuously expands the list of audited actions, but some operations (like viewing a file or reading a CI variable value) are not currently audited. Check the documentation for the complete list of audited events.