• Prerequisites
• Viewing audit events
  • Group audit events
  • Project audit events
  • Instance audit events
  • Sign-in audit events
• Exporting audit events
  • Audit event CSV encoding
• User impersonation
• Time zones
• Contribute to audit events

Audit events

A security audit is a in-depth analysis and review of your infrastructure, which is used to display areas of concern and potentially hazardous practices. To assist with the audit process, GitLab provides audit events which allow you to track a variety of different actions within GitLab.

For example, you can use audit events to track:

• Who changed the permission level of a particular user for a GitLab project, and when.
• Who added a new user or removed a user, and when.

These events can be used to in an audit to assess risk, strengthen security measures, respond to incidents, and adhere to compliance. For a complete list the audit events GitLab provides, see Audit event types.

Prerequisites

To view specific types of audit events, you need a minimum role.

• To view the group audit events of all users in a group, you must have the Owner role for the group.
• To view the project audit events of all users in a project, you must have at least the Maintainer role for the project.
• To view the group and project audit events based on your own actions in a group or project, you must have at least the Developer role for the group or project.

Users with the Auditor access level can see group and project events for all users.

Viewing audit events

Audit events can be viewed at the group, project, instance, and sign-in level. Each level has different audit events which it logs.

Group audit events

To view a group’s audit events:

1. On the left sidebar, select Search or go to and find your group.
2. Select Secure > Audit events.
3. Filter the audit events by the member of the project (user) who performed the action and date range.

Group audit events can also be accessed using the Group Audit Events API. Group audit event queries are limited to a maximum of 30 days.

Project audit events

1. On the left sidebar, select Search or go to and find your project.
2. Select Secure > Audit events.
3. Filter the audit events by the member of the project (user) who performed the action and date range.

Project audit events can also be accessed using the Project Audit Events API. Project audit event queries are limited to a maximum of 30 days.

Instance audit events

You can view audit events from user actions across an entire GitLab instance. To view instance audit events:

1. On the left sidebar, at the bottom, select Admin Area.
2. Select Monitoring > Audit Events.
3. Filter by the following:
   • Member of the project (user) who performed the action
   • Group
   • Project
   • Date Range

Sign-in audit events

Successful sign-in events are the only audit events available at all tiers. To see successful sign-in events:

1. On the left sidebar, select your avatar.
2. Select Edit profile > Authentication log.

After upgrading to a paid tier, you can also see successful sign-in events on audit event pages.

Exporting audit events

You can export the current view (including filters) of your instance audit events as a CSV(comma-separated values) file. To export the instance audit events to CSV:

1. On the left sidebar, at the bottom, select Admin Area.
2. Select Monitoring > Audit Events.
3. Select the available search filters.
4. Select Export as CSV.

A download confirmation dialog then appears for you to download the CSV file. The exported CSV is limited to a maximum of 100000 events. The remaining records are truncated when this limit is reached.

Audit event CSV encoding

The exported CSV file is encoded as follows:

• , is used as the column delimiter
• " is used to quote fields if necessary.
• \n is used to separate rows.

The first row contains the headers, which are listed in the following table along with a description of the values:

Column	Description
ID	Audit event id.
Author ID	ID of the author.
Author Name	Full name of the author.
Entity ID	ID of the scope.
Entity Type	Type of the scope (Project, Group, User, or Gitlab::Audit::InstanceScope).
Entity Path	Path of the scope.
Target ID	ID of the target.
Target Type	Type of the target.
Target Details	Details of the target.
Action	Description of the action.
IP Address	IP address of the author who performed the action.
Created At (UTC)	Formatted as YYYY-MM-DD HH:MM:SS.

All items are sorted by created_at in ascending order.

User impersonation

When a user is impersonated, their actions are logged as audit events with the following additional details:

• Audit events include information about the impersonating administrator.
• Extra audit events are recorded for the start and end of the administrator’s impersonation session.

Time zones

The time zone used for audit events depends on where you view them:

• In GitLab UI, your local time zone (GitLab 15.7 and later) or UTC (GitLab 15.6 and earlier) is used.
• The Audit Events API returns dates and times in UTC by default, or the configured time zone on a self-managed GitLab instance.
• In CSV exports, UTC is used.

Contribute to audit events

If you don’t see the event you want in any of the epics, you can either:

• Use the Audit Event Proposal issue template to create an issue to request it.
• Add it yourself.