Skip to content

GitLab

Audit Events (STARTER)

GitLab offers a way to view the changes made within the GitLab server for owners and administrators on a paid plan.

GitLab system administrators can also take advantage of the logs located on the file system. See the logs system documentation for more details.

You can generate an Audit report of audit events.

Overview

Audit Events is a tool for GitLab owners and administrators to track important events such as who performed certain actions and the time they happened. For example, these actions could be a change to a user permission level, who added a new user, or who removed a user.

Use cases

  • Check who changed the permission level of a particular user for a GitLab project.
  • Track which users have access to a certain group of projects in GitLab, and who gave them that permission level.

List of events

There are two kinds of events logged:

  • Events scoped to the group or project, used by group and project managers to look up who made a change.
  • Instance events scoped to the whole GitLab instance, used by your Compliance team to perform formal audits.

Impersonation data (PREMIUM)

Introduced in GitLab Premium 13.0.

Impersonation is where an administrator uses credentials to perform an action as a different user.

Group events (STARTER)

NOTE: Note: You need Owner permissions to view the group Audit Events page.

To view a group's audit events, navigate to Group > Settings > Audit Events. From there, you can see the following actions:

  • Group name or path changed.
  • Group repository size limit changed.
  • Group created or deleted.
  • Group changed visibility.
  • User was added to group and with which permissions.
  • User sign-in via Group SAML.
  • Permissions changes of a user assigned to a group.
  • Removed user from group.
  • Project repository imported into group.
  • Project shared with group and with which permissions.
  • Removal of a previously shared group with a project.
  • LFS enabled or disabled.
  • Shared runners minutes limit changed.
  • Membership lock enabled or disabled.
  • Request access enabled or disabled.
  • 2FA enforcement or grace period changed.
  • Roles allowed to create project changed.
  • Group CI/CD variable added, removed, or protected status changed. Introduced in GitLab 13.3.

Group events can also be accessed via the Group Audit Events API

Project events (STARTER)

NOTE: Note: You need Maintainer permissions or higher to view the project Audit Events page.

To view a project's audit events, navigate to Project > Settings > Audit Events. From there, you can see the following actions:

  • Added or removed deploy keys
  • Project created, deleted, renamed, moved (transferred), changed path
  • Project changed visibility level
  • User was added to project and with which permissions
  • Permission changes of a user assigned to a project
  • User was removed from project
  • Project export was downloaded
  • Project repository was downloaded
  • Project was archived
  • Project was unarchived
  • Added, removed, or updated protected branches
  • Release was added to a project
  • Release was updated
  • Release milestone associations changed
  • Permission to approve merge requests by committers was updated (introduced in GitLab 12.9)
  • Permission to approve merge requests by authors was updated (introduced in GitLab 12.9)
  • Number of required approvals was updated (introduced in GitLab 12.9)
  • Added or removed users and groups from project approval groups (introduced in GitLab 13.2)
  • Project CI/CD variable added, removed, or protected status changed (Introduced in GitLab 13.4)
  • User was approved via Admin Area (Introduced in GitLab 13.6)

Project events can also be accessed via the Project Audit Events API.

Instance events (PREMIUM ONLY)

Introduced in GitLab Premium 9.3.

Server-wide audit logging introduces the ability to observe user actions across the entire instance of your GitLab server, making it easy to understand who changed what and when for audit purposes.

To view the server-wide administrator log, visit Admin Area > Monitoring > Audit Log.

In addition to the group and project events, the following user actions are also recorded:

  • Sign-in events and the authentication type (such as standard, LDAP, or OmniAuth)
  • Failed sign-ins
  • Added SSH key
  • Added or removed email
  • Changed password
  • Ask for password reset
  • Grant OAuth access
  • Started or stopped user impersonation
  • Changed username (introduced in GitLab 12.8)
  • User was deleted (introduced in GitLab 12.8)
  • User was added (introduced in GitLab 12.8)
  • User was blocked via Admin Area (introduced in GitLab 12.8)
  • User was blocked via API (introduced in GitLab 12.9)
  • Failed second-factor authentication attempt (introduced in GitLab 13.5)
  • A user's personal access token was successfully created or revoked (introduced in GitLab 13.6)
  • A failed attempt to create or revoke a user's personal access token (introduced in GitLab 13.6)

It's possible to filter particular actions by choosing an audit data type from the filter dropdown box. You can further filter by specific group, project, or user (for authentication events).

audit log

Instance events can also be accessed via the Instance Audit Events API.

Missing events

Some events are not tracked in Audit Events. See the following epics for more detail on which events are not being tracked, and our progress on adding these events into GitLab:

Disabled events

Repository push

The current architecture of audit events is not prepared to receive a very high amount of records. It may make the user interface for your project or audit logs very busy, and the disk space consumed by the audit_events PostgreSQL table may increase considerably. It's disabled by default to prevent performance degradations on GitLab instances with very high Git write traffic.

In an upcoming release, Audit Logs for Git push events will be enabled by default. Follow #7865 for updates.

If you still wish to enable Repository push events in your instance, follow the steps bellow.

In Omnibus installations:

  1. Enter the Rails console:

    sudo gitlab-rails console

  2. Flip the switch and enable the feature flag:

    Feature.enable(:repository_push_audit_event)

Retention policy

On GitLab.com, Audit Event records become subject to deletion after 400 days, or when your license is downgraded to a tier that does not include access to Audit Events. Data that is subject to deletion will be deleted at GitLab's discretion, possibly without additional notice.

If you require a longer retention period, you should independently archive your Audit Event data, which you can retrieve through the Audit Events API.

Export to CSV (PREMIUM ONLY)

CAUTION: Warning: This feature might not be available to you. Check the version history note above for details. If available, you can enable it with a feature flag.

Export to CSV allows customers to export the current filter view of your audit log as a CSV file, which stores tabular data in plain text. The data provides a comprehensive view with respect to audit events.

To export the Audit Log to CSV, navigate to {monitor} Admin Area > Monitoring > Audit Log

  1. Click in the field Search.
  2. In the dropdown menu that appears, select the event type that you want to filter by.
  3. Select the preferred date range.
  4. Click Export as CSV.

Export Audit Log

Sort

Exported events are always sorted by ID in ascending order.

Format

Data is encoded with a comma as the column delimiter, with " used to quote fields if needed, and newlines 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 entity (Project/Group/User)
Entity Path Path of the entity
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

Limitation

The Audit Log CSV file size is limited to a maximum of 100,000 events. The remaining records are truncated when this limit is reached.

Enable or disable Audit Log Export to CSV

The Audit Log Export to CSV is under development and not ready for production use. It is deployed behind a feature flag that is disabled by default. GitLab administrators with access to the GitLab Rails console can enable it.

To enable it:

Feature.enable(:audit_log_export_csv)

To disable it:

Feature.disable(:audit_log_export_csv)