2020-05-07 21:09:26 +00:00
---
2020-06-08 18:08:27 +00:00
stage: Manage
2020-07-22 21:09:50 +00:00
group: Compliance
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-07 21:09:26 +00:00
---
2021-02-04 18:09:22 +00:00
# Audit Events **(PREMIUM)**
2019-05-05 15:21:25 +00:00
2020-04-21 15:21:10 +00:00
GitLab offers a way to view the changes made within the GitLab server for owners and administrators on a [paid plan ](https://about.gitlab.com/pricing/ ).
2019-05-05 15:21:25 +00:00
GitLab system administrators can also take advantage of the logs located on the
2021-02-05 18:09:44 +00:00
file system. See [the logs system documentation ](logs.md#audit_jsonlog ) for more details.
2019-05-05 15:21:25 +00:00
2020-11-10 18:09:07 +00:00
You can generate an [Audit report ](audit_reports.md ) of audit events.
2019-05-05 15:21:25 +00:00
## Overview
2020-02-20 18:08:51 +00:00
**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
2019-05-05 15:21:25 +00:00
permission level, who added a new user, or who removed a user.
2020-02-20 18:08:51 +00:00
## Use cases
2019-05-05 15:21:25 +00:00
2020-02-20 18:08:51 +00:00
- 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.
2019-05-05 15:21:25 +00:00
## List of events
There are two kinds of events logged:
2020-02-20 18:08:51 +00:00
- Events scoped to the group or project, used by group and project managers
to look up who made a change.
2019-05-05 15:21:25 +00:00
- Instance events scoped to the whole GitLab instance, used by your Compliance team to
perform formal audits.
2021-02-12 21:09:01 +00:00
### Impersonation data
2020-05-15 15:08:04 +00:00
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0.
2020-05-15 15:08:04 +00:00
2021-02-12 21:09:01 +00:00
When a user is being [impersonated ](../user/admin_area/index.md#user-impersonation ), their actions are logged as audit events as usual, with two additional details:
1. Usual audit events include information about the impersonating administrator. These are visible in their respective Audit Event pages depending on their type (Group/Project/User).
1. Extra audit events are recorded for the start and stop of the administrator's impersonation session. These are visible in the instance Audit Events.
![audit events ](img/impersonated_audit_events_v13_8.png )
2020-05-15 15:08:04 +00:00
2021-02-04 18:09:22 +00:00
### Group events **(PREMIUM)**
2019-05-05 15:21:25 +00:00
2020-12-16 15:10:18 +00:00
A user with a Owner role (or above) can retrieve group audit events of all users.
A user with a Developer or Maintainer role is limited to group audit events based on their individual actions.
2019-05-05 15:21:25 +00:00
2020-12-16 15:10:18 +00:00
To view a group's audit events, navigate to **Group > Security & Compliance > Audit Events** .
2019-05-05 15:21:25 +00:00
From there, you can see the following actions:
2020-08-18 06:10:30 +00:00
- 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/permissions.md ).
- User sign-in via [Group SAML ](../user/group/saml_sso/index.md ).
- Permissions changes of a user assigned to a group.
- Removed user from group.
- Project repository imported into group.
2019-05-05 15:21:25 +00:00
- [Project shared with group ](../user/project/members/share_project_with_groups.md )
2020-08-18 06:10:30 +00:00
and with which [permissions ](../user/permissions.md ).
- 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 ](https://gitlab.com/gitlab-org/gitlab/-/issues/30857 ) in GitLab 13.3.
2019-05-05 15:21:25 +00:00
2020-09-07 15:09:04 +00:00
Group events can also be accessed via the [Group Audit Events API ](../api/audit_events.md#group-audit-events )
2019-11-15 03:06:34 +00:00
2021-02-04 18:09:22 +00:00
### Project events **(PREMIUM)**
2019-05-05 15:21:25 +00:00
2020-12-16 15:10:18 +00:00
A user with a Maintainer role (or above) can retrieve project audit events of all users.
A user with a Developer role is limited to project audit events based on their individual actions.
2019-05-05 15:21:25 +00:00
2020-12-16 15:10:18 +00:00
To view a project's audit events, navigate to **Project > Security & Compliance > Audit Events** .
2019-05-05 15:21:25 +00:00
From there, you can see the following actions:
2020-02-20 18:08:51 +00:00
- Added or removed deploy keys
2020-06-26 15:08:45 +00:00
- Project created, deleted, renamed, moved (transferred), changed path
2019-05-05 15:21:25 +00:00
- Project changed visibility level
2020-04-21 15:21:10 +00:00
- User was added to project and with which [permissions ](../user/permissions.md )
2019-05-05 15:21:25 +00:00
- Permission changes of a user assigned to a project
- User was removed from project
2019-07-24 14:15:50 +00:00
- Project export was downloaded
- Project repository was downloaded
2019-08-21 03:42:48 +00:00
- Project was archived
- Project was unarchived
2020-02-20 18:08:51 +00:00
- Added, removed, or updated protected branches
2020-01-10 18:07:43 +00:00
- Release was added to a project
- Release was updated
- Release milestone associations changed
2020-05-21 06:08:25 +00:00
- Permission to approve merge requests by committers was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9)
- Permission to approve merge requests by authors was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9)
- Number of required approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9)
2020-07-13 18:09:16 +00:00
- Added or removed users and groups from project approval groups ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213603) in GitLab 13.2)
2020-10-23 18:08:31 +00:00
- Project CI/CD variable added, removed, or protected status changed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.4)
2021-01-22 21:09:10 +00:00
- Project access token was successfully created or revoked ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9)
- Failed attempt to create or revoke a project access token ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9)
2021-02-02 00:09:14 +00:00
- When default branch changes for a project ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/52339) in GitLab 13.9)
2019-05-05 15:21:25 +00:00
2020-10-23 18:08:31 +00:00
Project events can also be accessed via the [Project Audit Events API ](../api/audit_events.md#project-audit-events ).
2020-06-04 00:08:17 +00:00
2021-01-13 00:10:50 +00:00
Project event queries are limited to a maximum of 30 days.
2021-01-28 12:09:54 +00:00
### Instance events **(PREMIUM SELF)**
2019-05-05 15:21:25 +00:00
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3.
2019-05-05 15:21:25 +00:00
2020-12-14 06:09:41 +00:00
Server-wide audit events introduce the ability to observe user actions across
2019-05-05 15:21:25 +00:00
the entire instance of your GitLab server, making it easy to understand who
changed what and when for audit purposes.
2020-12-14 06:09:41 +00:00
To view the server-wide administrator log, visit **Admin Area > Monitoring > Audit Events** .
2019-05-05 15:21:25 +00:00
In addition to the group and project events, the following user actions are also
recorded:
2020-02-20 18:08:51 +00:00
- Sign-in events and the authentication type (such as standard, LDAP, or OmniAuth)
2020-10-23 18:08:31 +00:00
- Failed sign-ins
2019-05-05 15:21:25 +00:00
- Added SSH key
2020-02-20 18:08:51 +00:00
- Added or removed email
2019-05-05 15:21:25 +00:00
- Changed password
- Ask for password reset
- Grant OAuth access
2020-02-20 18:08:51 +00:00
- Started or stopped user impersonation
2020-05-21 06:08:25 +00:00
- Changed username ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7797) in GitLab 12.8)
- User was deleted ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8)
- User was added ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8)
2021-01-28 06:08:59 +00:00
- User requests access to an instance ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9)
- User was approved via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276250) in GitLab 13.6)
- User was rejected via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9)
2020-05-21 06:08:25 +00:00
- User was blocked via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8)
2020-03-04 12:07:52 +00:00
- User was blocked via API ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25872) in GitLab 12.9)
2020-09-30 03:09:46 +00:00
- Failed second-factor authentication attempt ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16826) in GitLab 13.5)
2020-11-09 12:09:24 +00:00
- A user's personal access token was successfully created or revoked ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6)
- A failed attempt to create or revoke a user's personal access token ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6)
2019-05-05 15:21:25 +00:00
2020-10-23 18:08:31 +00:00
Instance events can also be accessed via the [Instance Audit Events API ](../api/audit_events.md#instance-audit-events ).
2019-11-15 03:06:34 +00:00
2019-05-05 15:21:25 +00:00
### Missing events
2020-02-20 18:08:51 +00:00
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
2019-05-05 15:21:25 +00:00
on adding these events into GitLab:
- [Project settings and activity ](https://gitlab.com/groups/gitlab-org/-/epics/474 )
- [Group settings and activity ](https://gitlab.com/groups/gitlab-org/-/epics/475 )
- [Instance-level settings and activity ](https://gitlab.com/groups/gitlab-org/-/epics/476 )
2021-04-30 00:10:28 +00:00
Don't see the event you want in any of the epics linked above? You can use the **Audit Event
Proposal** issue template to
[create an issue ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Audit%20Event%20Proposal )
to request it.
2019-09-23 18:06:14 +00:00
### Disabled events
#### Repository push
The current architecture of audit events is not prepared to receive a very high amount of records.
2020-12-14 06:09:41 +00:00
It may make the user interface for your project or audit events very busy, and the disk space consumed by the
2020-09-29 21:09:35 +00:00
`audit_events` PostgreSQL table may increase considerably. It's disabled by default
2019-09-23 18:06:14 +00:00
to prevent performance degradations on GitLab instances with very high Git write traffic.
2020-12-14 06:09:41 +00:00
In an upcoming release, Audit Events for Git push events will be enabled
2021-03-02 18:11:20 +00:00
by default. Follow our [Partitioning strategy for Audit Events epic ](https://gitlab.com/groups/gitlab-org/-/epics/3206 ) for updates.
2019-09-23 18:06:14 +00:00
If you still wish to enable **Repository push** events in your instance, follow
2021-05-17 09:10:26 +00:00
the steps below.
2019-09-23 18:06:14 +00:00
**In Omnibus installations:**
1. Enter the Rails console:
2020-01-30 15:09:15 +00:00
```shell
2019-09-23 18:06:14 +00:00
sudo gitlab-rails console
```
1. Flip the switch and enable the feature flag:
```ruby
Feature.enable(:repository_push_audit_event)
2020-09-30 03:09:46 +00:00
```
2020-09-18 00:09:39 +00:00
2020-11-24 18:09:14 +00:00
## Search
The search filters you can see depends on which audit level you are at.
| Filter | Available options |
| ------ | ----------------- |
| Scope (Project level) | A specific user who performed the action. |
| Scope (Group level) | A specific user (in a group) who performed the action. |
| Scope (Instance level) | A specific group, project, or user that the action was scoped to. |
| Date range | Either via the date range buttons or pickers (maximum range of 31 days). Default is from the first day of the month to today's date. |
2020-12-14 06:09:41 +00:00
![audit events ](img/audit_log_v13_6.png )
2020-11-24 18:09:14 +00:00
2021-01-28 12:09:54 +00:00
## Export to CSV **(PREMIUM SELF)**
2020-09-18 00:09:39 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4.
2020-11-30 09:09:17 +00:00
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7.
2020-09-18 00:09:39 +00:00
2020-12-14 06:09:41 +00:00
Export to CSV allows customers to export the current filter view of your audit events as a
2020-11-24 18:09:14 +00:00
CSV file, which stores tabular data in plain text. The data provides a comprehensive view with respect to
2020-09-18 00:09:39 +00:00
audit events.
2020-12-14 06:09:41 +00:00
To export the Audit Events to CSV, navigate to
**{monitor}** **Admin Area > Monitoring > Audit Events**
2020-09-18 00:09:39 +00:00
2020-11-24 18:09:14 +00:00
1. Select the available search [filters ](#search ).
2020-09-18 00:09:39 +00:00
1. Click **Export as CSV** .
### Sort
2020-11-24 18:09:14 +00:00
Exported events are always sorted by `created_at` in ascending order.
2020-09-18 00:09:39 +00:00
### 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 |
2020-11-24 18:09:14 +00:00
| Entity Type | Type of the scope (`Project`/`Group`/`User`) |
| Entity Path | Path of the scope |
2020-09-18 00:09:39 +00:00
| 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
2020-12-14 06:09:41 +00:00
The Audit Events CSV file is limited to a maximum of `100,000` events.
2020-09-18 00:09:39 +00:00
The remaining records are truncated when this limit is reached.