GitLab audit events and streaming

How GitLab audit events answer who changed what

When an auditor, security lead or platform owner asks who changed an administrator setting, a group membership or a project visibility rule in self-managed GitLab, the answer has to come from a record that the people being audited do not control. GitLab audit events are that record. They capture changes made to instance, group and project configuration, along with the actor, the target, the time and the change details, so a reviewer can reconstruct a sequence of events rather than rely on memory or screenshots. Before you design anything around them, confirm in the GitLab documentation for your exact version and tier which event types are recorded, because coverage has grown across releases and some events are tier-specific.

Teams stream audit events out of GitLab for two reasons. The first is retention and independence: a copy in a SIEM or object storage outlives instance maintenance, restores and any single administrator's access to the GitLab database. The second is correlation: a change to a protected branch or a new access token is more useful when it sits next to sign-in logs from your identity provider and alerts from other systems. Streaming also raises questions you should settle early, including which destination is the system of record, how events are authenticated and how gaps are detected if the stream stops. Those answers depend on the streaming options your version offers, so check them against the audit event streaming documentation rather than assuming a generic webhook or syslog path.

Plan the decision as a short checklist before the build starts. List the change types your auditors have asked about in the last audit cycle, map each one to a documented event for your version, and note the tier each requires. Then test in a non-production instance: make a known administrator change, a group permission change and a project visibility change, and confirm each appears at the destination with the expected actor and timestamp. Ask your GitLab contact or review the release notes for any event you cannot find. Keep the test results as evidence, since they show the stream works, which is a separate question from whether your control design satisfies an auditor.

Choosing between SIEM streaming and stored exports

This table compares three ways to get GitLab audit events out of the instance: streaming to a SIEM, periodic export to object storage, and API reads for ad hoc review. Read each row against your receiving team's capacity and your retention obligations, then confirm the tier and feature details for your exact GitLab version before you commit.

Option	When it fits	What the receiving team must run	Retention responsibility	What to confirm with GitLab for your version
Stream to a SIEM over a network protocol	Security operations needs near-real-time alerting on administrator and permission changes	A SIEM listener or collector, network paths from GitLab, and alert rules for event types	Retention sits in the SIEM, so its storage and archive policy must match your obligations	Which event types stream, supported destination protocols, and whether streaming is available on your tier
Periodic export to object storage	Compliance teams need durable, low-cost copies of change history for review and audit	Object storage buckets, lifecycle and access policies, and a process to load or query exports	Your team owns the bucket, its retention rules, immutability settings and deletion controls	Export format, schedule options, and whether the feature exists on your edition and version
Read through the API for ad hoc review	Investigators need to answer a specific question about a project or group after the fact	A script or tool with a scoped access token, plus a record of queries and results	Nothing is kept by GitLab beyond its own retention, so copies you need must be saved separately	Which audit endpoints exist, their pagination and date filters, and what history GitLab keeps and for how long
Coverage of administrator actions	Required for most change-control reviews of instance-wide settings	Mapping of event types to your control library so each change type has a detection or review step	Keep administrator events in the same retention scope as project and group events	Which administrator events are recorded in your version and whether they reach each delivery path
Coverage of group and project changes	Needed to show who changed access, protected branches or pipeline settings	Filters and dashboards that separate routine from high-risk changes	Define a retention period per event class in writing with the compliance owner	Which group and project events are logged in your version and at which tier they appear
Delivery gaps and replay	Any path where a stream or export can fail silently	Monitoring for delivery errors, queue backlog and export job failures, plus a replay plan	Gaps in delivery become gaps in evidence, so record failures and the recovery steps taken	How GitLab reports failed deliveries and whether events can be resent
Tamper resistance of stored copies	Evidence must be hard to alter after capture	Write-once or versioned storage, restricted delete rights and hash or checksum records	Keep copies under separate administrative control from the GitLab instance	Whether exports are signed or immutable and how to verify them
Cost drivers	Volume grows with user count, CI activity and the number of enabled event types	Ingest and storage capacity in the SIEM or bucket, plus engineering time to build parsers	Storage cost recurs for the full retention period, so plan retention before volume grows	Expected event volume for your instance, and how licensing or ingest pricing applies to the receiving product

Which audit scopes to confirm for your tier

Instance-level events cover what administrators do to the whole GitLab installation, such as changing sign-up and authentication settings, adding or removing administrators, altering application settings and changing integrations that affect every group. These events matter most in an assessment because they show who could change the controls that govern everything else. Confirm the event types for your version in the GitLab audit event documentation, and check the tier table on the GitLab pricing page before you promise a specific event or report to an auditor. Premium and Ultimate differ in compliance features as listed on that page, so do not assume a Premium instance has the same reporting as an Ultimate one.

Admin role changes: Confirm who can grant or remove administrator access and whether those changes are recorded with the acting user.
Authentication settings: Check whether changes to sign-in methods, two-factor requirements and sign-up rules are captured.
Application settings: Review which global settings produce an event and how the before and after values appear.
Retention: Confirm how long events remain in the instance before export or deletion.

Auditors usually ask for a dated list of administrator changes, the approver of each change and proof that the list is complete for the period under review.

How to set up audit event streaming safely

This sequence takes a GitLab audit event stream from a confirmed tier and version to a tested destination with alerting and a runbook, so that administrator, group and project changes reach your SIEM or storage in a form your compliance owner can rely on.

Confirm tier and version
The platform administrator confirms the GitLab edition and tier on the instance, then checks the installed version against the maintenance policy and the currently maintained release lines. Ask your GitLab account contact or review the pricing page to confirm which tier includes the audit event streaming and external destination features you plan to use, because those features are tier-dependent and the exact feature list changes between releases. Record the installed version and the tier in the change ticket. The step is done when you can name the tier, the version and the documentation page that confirms the feature is available on both.
Define audit scope and retention with compliance
Work with the compliance owner to list which events must be captured, such as administrator actions, group membership and permission changes, project visibility changes, and token or deploy key events, and which entities they cover, including top-level groups and subgroups. Agree on how long events must be retained in the destination and who may query them. Write the scope as a short table so that engineers and auditors read the same definition. The step is done when the compliance owner signs off on the scope and retention requirement, and you can point to that sign-off in the design record.
Choose destination and ingest method
Decide where events land: a SIEM, a log platform, or object storage for long-term retention. Confirm how the destination ingests the format GitLab emits, whether it needs a parser or a mapping for the event fields, and whether it can run inside your network or air-gapped boundary. If you plan to use Wazuh or another SIEM you operate, verify the ingest path in its own documentation before committing. The step is done when you have a written data flow diagram naming the source, transport, destination and the team that owns each hop.
Configure the target with restricted credentials
Create the streaming or export target in GitLab using a dedicated endpoint and a credential that can only write to that destination. Store the secret in your approved secrets manager rather than in plain configuration, restrict who can view or rotate it, and set a rotation owner. Confirm that the transport uses encrypted connections where the destination supports them, and that the destination rejects writes from any other source. The step is done when the target shows as configured, the credential scope has been reviewed by a second person, and the rotation owner is recorded.
Send a test change in a non-production group
Create a non-production test group and a project inside it. Make a controlled set of changes: add and remove a member, change a project visibility setting, and create and revoke an access token. Then search the destination for those events within the time you expect for delivery. Check that each event carries the actor, the target, the action, the timestamp and the group or project path, and that the fields match your scope from the earlier step. Compare the output with the GitLab audit event view for the same actions. The step is done when every test action appears at the destination with the expected fields, and any gaps are logged as defects before go-live.
Alert on delivery failures
Configure monitoring that fires when the destination stops receiving events, when the endpoint returns errors, or when the credential is rejected. Test the alert by temporarily disabling the destination in a non-production setting and confirming that the on-call channel receives the notification. Decide the owner who responds and what counts as a gap that must be backfilled from GitLab. Verify the alert path inside your own environment, since monitoring tools and on-call systems differ. The step is done when a deliberate failure produces a notification to the named owner within your agreed response process.
Document the runbook and hand over
Write a runbook covering the configured target, the credential and rotation owner, the field mapping, the test procedure, the alert response, and the steps to recover missed events when delivery fails. Include the GitLab version and tier used, and schedule a review each time the GitLab version changes, since upgrades can affect event formats and available features. Walk the platform, security and compliance teams through the runbook and retain the approved copy with the change record. The step is done when each named owner has accepted the runbook and a retest date is on the calendar.

Security risks in audit trails and how to contain them

An audit trail is only useful if it is complete, accurate, readable by the right people and protected from the people it records. The cards below cover the risks we see most often when GitLab audit events are streamed to a SIEM or storage, each paired with the control to plan and the owner who should sign off before go-live.

Over-privileged destination credentials

The token or key GitLab uses to send events to the SIEM or storage bucket often ends up with broad rights, such as write and delete access to the whole index or bucket. Scope the credential to append-only writes to one destination, store it in your secrets manager, and rotate it on a schedule. The owner is the security operations lead, who should confirm the exact permissions the destination requires.

Events lost during a destination outage

If the SIEM or storage endpoint is unreachable, events can be dropped rather than held for later delivery. Ask for the retry and buffering behavior in writing, decide how long a gap is tolerable, and monitor delivery failures as a signal in their own right. The platform engineering lead should own the outage test that proves this works, and the compliance lead should accept the documented gap window.

Administrators able to edit the record

GitLab administrators can change instance settings, and a copy of the audit log kept only inside GitLab is only as trustworthy as those accounts. Forward events to a destination that GitLab administrators cannot modify, restrict who holds destination admin rights, and keep those rights separate from GitLab administration. The CISO or audit owner should approve who can read and who can change the stored record.

Personal data in audit payloads

Audit events record who changed what, and some payloads can include user names, email addresses or IP addresses that carry personal data obligations. Map which fields leave GitLab, decide retention and access for each destination, and confirm with GitLab which fields each event type contains in your version. The data protection officer should sign off on the field map and retention period.

Clock drift breaking timelines

Investigators rebuild incidents by ordering events across GitLab, runners and the SIEM, so unsynchronized clocks can place a change before the approval that authorized it. Run time synchronization on every GitLab node and the destination, record the time zone the destination stores, and test ordering with a known change. The infrastructure owner should confirm synchronization on each host before the audit feed is trusted.

Unencrypted streaming channel

If events travel over a plain HTTP connection or an unverified TLS endpoint, both confidentiality and integrity of the record are exposed in transit. Require TLS to the destination, verify the certificate chain against your internal authority, and confirm the destination accepts only encrypted connections. The network security lead should own the verification, and the architect should confirm the path crosses no untrusted network segment.

Running audit streams after go-live

Once the stream is live, the first day-two task is proving that it is still complete. Set a recurring check that compares event counts in the destination against administrator, group and project changes recorded in GitLab over the same window. Alert when a source goes quiet for longer than its normal activity pattern, and treat a sudden drop in permission-change or administrator events as an incident to investigate. Silence is the failure most teams miss. Confirm with your GitLab administrator which audit categories your tier and configuration actually send, record that list as the baseline, and check the log shipper or queue for backlog after restarts and network outages.

Upgrades change the shape of the event data. GitLab ships a minor release on the third Thursday of each month and a major release each year, and required upgrade stops fall at versions x.2, x.5, x.8 and x.11, so plan a field check after every upgrade you apply, not only the yearly ones. Compare a sample of new events in the destination against the release notes and the audit event documentation, looking for renamed fields, new event types that your Wazuh decoders or SIEM parsing rules drop, and changed user or timestamp formats. Wazuh's own release line also moves, with 4.14 patch releases arriving roughly every one to two months according to its release notes, so schedule rule and decoder reviews on that rhythm too. Test each rule change in a non-production environment and keep the previous version available for rollback.

Rehearse the evidence pull before an auditor asks for it. Choose a question an auditor is likely to ask, such as who changed a protected branch setting during a given quarter, and time how long it takes to answer from the SIEM or storage location alone, without asking an administrator to export anything from GitLab. The rehearsal should show that the evidence is complete and retrievable by someone other than the person who built the pipeline. Record the queries used, the retention period for each source, and who holds access to the destination. Repeat the exercise after each change to the stream or storage tier. Confirm with your auditor which period, format and chain-of-custody details they expect, because DeployOpen prepares the evidence and does not issue the audit opinion.

What to confirm in your environment before relying on audit streams

Audit events are only useful as evidence if you know what GitLab emits in your version, where it can go, and how long it survives. The cards below list the limits to confirm with GitLab documentation, your tier, and your own network and retention requirements before you design around them.

Events emitted in your version

Coverage of administrator, group and project audit events changes between GitLab releases, so the event list for the version you run is what matters, not the list you saw in a demo. Check which actions are recorded (permission changes, token creation, membership changes, settings changes) and which are not. Ask GitLab for the exact event catalog for your release, then test each action you must evidence in a non-production instance and confirm the event appears with the fields your auditors need, such as actor, target and timestamp.

Destination type support

Confirm that the streaming destination type you plan to use, such as an HTTP endpoint, a specific SIEM or object storage, is supported by your GitLab version and tier. Do not assume a vendor integration exists because a generic endpoint does. If you rely on a custom receiver, ask whether the payload format, authentication method and TLS requirements match what your receiver can accept, and whether the format is stable across upgrades.

Delivery guarantees and retries

Find out whether delivery is at least once, at most once or best effort, and what GitLab does when the destination is down or returns an error. Ask how many retries happen, over what period, and whether events are dropped after the retry window. Confirm whether a gap in delivery can be detected and backfilled from the instance's own records, because a SIEM that silently misses events undermines the stream.

Retention in GitLab and the destination

Audit events kept inside GitLab and events held by the receiving system follow different retention rules, and each must meet your policy. Ask GitLab how long events remain queryable in the instance and whether older events are purged automatically. Then confirm the retention, immutability and storage tier of your SIEM or bucket, since a short destination window can defeat a longer requirement set for the instance.

Air-gapped and offline operation

A stream that depends on a cloud collector, an external SaaS receiver or a public certificate authority will not work in an offline network without changes. Confirm that every component in the path, including the destination, time synchronization and certificate trust, can run inside your boundary. GitLab documents running self-managed instances offline, but the audit streaming path itself needs to be checked against your network rules for your release.

Tier and feature entitlement

Confirm in writing which tier includes the audit event and streaming features you plan to use, because Free, Premium and Ultimate differ and the pricing page does not map every audit capability line by line. Ask the vendor whether a feature is available on self-managed installations at your tier, and whether any part of the design depends on an add-on. Record the answer against the GitLab version you will deploy, since entitlements can change between releases.

Retention and evidence duties that shape the design

Start with three questions your compliance lead can answer before any collector is configured: how long each class of administrator, group and project change must be kept, whether any of it may be placed under legal hold, and how an auditor will sample it. The retention period sets how much history the audit store must hold and where it lives, so a seven-year requirement points toward archival storage rather than a short-lived SIEM index. Legal hold means specific records must survive deletion or rotation on demand, which requires a process to export and freeze them, not just a longer retention setting. Sampling method matters because auditors who pick a random change from a month and ask for its approver and timestamp need every event searchable by date, user and project, with the original fields intact.

GitLab backups and audit event streams are separate evidence paths, and they should not be treated as interchangeable. A backup captures the state of the instance at a point in time, so it shows what a project or setting looked like, but it does not show the sequence of who changed what in between. Audit events record those changes as they happen and can be forwarded to a SIEM or object storage, but they depend on the streaming destination staying healthy and on the instance keeping its own audit history for the period the streaming configuration covers. Confirm with your compliance lead which copy is the system of record, how the other is used to corroborate it, and whether both are retained on the same schedule. Verify the audit streaming setup against the current GitLab documentation for your tier and version.

DeployOpen prepares the controls, configuration and evidence that support these decisions, including retention settings, streaming destinations, access to the audit store and documented test restores. DeployOpen does not issue audit reports, attestations or certifications. Those come from the independent auditor or certification body your organization engages, and the auditor decides whether the evidence meets the applicable criteria. Agree the evidence list with both your compliance lead and the auditor before the build starts, so the implementation produces what will actually be requested.

What does audit event streaming cost and take to set up?

What drives the cost of streaming GitLab audit events to a SIEM?

Cost comes from four parts: the GitLab tier that includes the audit capabilities you need, the capacity of the destination (SIEM indexing or object storage, which grows with event volume and retention), engineering time to configure and test streams, and the SIEM rules and dashboards your team maintains afterward. GitLab's pricing page lists Free at 0 US dollars and Premium at 29 US dollars per user per month billed annually, with Ultimate custom priced, and all three tiers are available for self-managed installations. The page does not map each audit feature to a tier, so confirm that mapping on the GitLab pricing page before you budget. Licensing recurs per user. Stream configuration and parser work are mostly one-time. Storage and rule upkeep recur.

How long does audit event streaming setup usually take?

No general duration applies, because the timeline depends on the work in front of you. The main variables are the number of GitLab instances and top-level groups in scope, whether the destination is an existing SIEM or a new one, how much event parsing and field mapping the SIEM team needs, which event types you filter in or out, and how long your change approval and test window take. A simple single-instance stream into an existing SIEM takes far less effort than a multi-instance design with custom parsing and retention rules. Ask for the timeline as milestones in the written scope, with each dependency on your side named. DeployOpen agrees timelines in writing before work starts, and most engagements are fixed-scope.

What does the client need to provide for audit event streaming work?

The work needs named people more than it needs tools. Plan for these inputs:

A GitLab administrator who can open the Admin Area and confirm the audit settings, tier and instance details.
A SIEM owner who decides the index, parsing rules, retention and alert use of the events.
A security or compliance sponsor who defines which administrator, group and project changes must be captured.
Network contacts who can open and verify the path from GitLab to the destination.
A test window in which administrators make controlled changes and the SIEM team confirms the events arrived intact.

Agree these owners and the test window at scoping, because delays on any one of them usually hold up the whole plan.

Can an internal team set up audit event streaming on its own?

An internal team can do it if it has GitLab administration skills, SIEM engineering skills and time for testing. The harder parts are usually not the transport. They are deciding which changes count as evidence, mapping event fields so analysts can query them, setting retention that matches your policy, and proving the stream works after each upgrade. Confirm that your team has someone who can own each of those decisions after handover. If capacity is the constraint, a partner can take on the build under a fixed scope and move the operating work to a retainer for ongoing support and upgrades. Either way, write down who owns each stream and each SIEM rule before go-live.

How do I get an accurate quote for audit event streaming?

A quote follows from a written scope. DeployOpen does not publish a price list, so the scope is what makes the quote comparable. Ask the provider to state the GitLab tier and number of instances, the event types in and out of scope, the destination and its version, the parsing and dashboard work, the test cases and acceptance criteria, the documentation and handover, and any ongoing support. Also ask which items are one-time and which recur, which items the client must supply, and which items are excluded. Compare quotes against the same scope. A quote that is cheaper because it omits testing or handover is not a like-for-like comparison.

How do GitLab upgrades change an audit event stream?

Upgrades change the work in two ways: they follow required paths, and they can change what the stream sends. GitLab requires upgrades to pass through upgrade stops, which since GitLab 17.5 fall at x.2, x.5, x.8 and x.11, such as 19.5, 19.8 and 19.11. GitLab ships a minor release on the third Thursday of each month and patch releases twice a month, and it maintains 19.5, 19.4 and 19.3 at the time of writing. Bug fixes are backported only to the current stable release, while security fixes also reach the previous two monthly releases. After each upgrade, re-run the stream tests and check the GitLab upgrade paths documentation for required stops. Ask whether ongoing upgrade support is part of the scope.

Can Wazuh receive GitLab audit events as a SIEM destination?

Wazuh is a possible destination, but confirm the ingestion route for GitLab audit events before you commit to it. Wazuh is distributed under the GNU General Public License version 2, with an exception that permits linking with OpenSSL, so license review is a standard step. Its components include an indexer for alert storage, a server that applies decoders and rules, a dashboard, and agents. Wazuh also supports agentless collection through syslog. Its current release line is 4.14, and 4.14.9 was released on 14 October 2026. Check the Wazuh deployment options and your GitLab version together, and test the decoders and rules on sample events before you rely on them for detection.

How DeployOpen scopes and delivers GitLab audit logging

DeployOpen starts by agreeing which GitLab audit events matter to your auditors and security team, and which tier your current or planned edition provides for them. We then build the recording and streaming path inside infrastructure you control, and hand over documented, tested configuration that your team can operate.

How we scope

Confirm the GitLab edition and tier needed for each audit capability before any build starts
List the administrator, group and project change events your audit and security teams require
Record the SIEM or storage destination, retention expectations and network path in the written scope
Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work begins

How we build

Configure audit event review and streaming on the instance, then validate event delivery end to end
Test that administrator, group and project changes arrive at the SIEM or storage with expected fields
Plan for air-gapped or restricted networks where the destination sits outside the GitLab network
Protect the streaming credentials and endpoints using the access controls agreed in the scope

How we hand over

Document the configured events, destinations, filters, retention settings and verification steps
Provide runbooks for adding new destinations, rotating credentials and investigating missing events
Walk your administrators and security engineers through the configuration and the test evidence
Provide a clear record of what was configured so your compliance team can review it independently

How we support

Ongoing support, upgrades and continuous testing are available as a retainer
Review audit event coverage again when GitLab upgrades change event types or tier availability
Confirm streaming still works after upgrades, SIEM changes or network changes
Ask about retainer scope, response expectations and review cadence when requesting a quote