2020-05-07 21:09:26 +00:00
---
stage: Monitor
group: APM
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/#designated-technical-writers
---
2019-07-08 08:50:38 +00:00
# Audit Events **(STARTER)**
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
2020-02-20 18:08:51 +00:00
filesystem. See [the logs system documentation ](logs.md ) for more details.
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.
2020-05-15 15:08:04 +00:00
### Impersonation data **(PREMIUM)**
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
Impersonation is where an administrator uses credentials to perform an action as a different user.
2019-07-08 08:50:38 +00:00
### Group events **(STARTER)**
2019-05-05 15:21:25 +00:00
NOTE: **Note:**
2020-04-21 15:21:10 +00:00
You need Owner [permissions ](../user/permissions.md ) to view the group Audit Events page.
2019-05-05 15:21:25 +00:00
To view a group's audit events, navigate to **Group > Settings > Audit Events** .
From there, you can see the following actions:
2020-02-20 18:08:51 +00:00
- Group name or path changed
2019-05-05 15:21:25 +00:00
- Group repository size limit changed
2020-02-20 18:08:51 +00:00
- Group created or deleted
2019-05-05 15:21:25 +00:00
- Group changed visibility
2020-04-21 15:21:10 +00:00
- User was added to group and with which [permissions ](../user/permissions.md )
2020-04-07 12:09:34 +00:00
- User sign-in via [Group SAML ](../user/group/saml_sso/index.md )
2019-05-05 15:21:25 +00:00
- Permissions changes of a user assigned to a group
- Removed user from group
2020-05-11 15:09:37 +00:00
- Project imported in to group
2019-05-05 15:21:25 +00:00
- Project added to group and with which visibility level
- Project removed from group
- [Project shared with group ](../user/project/members/share_project_with_groups.md )
2020-04-21 15:21:10 +00:00
and with which [permissions ](../user/permissions.md )
2019-05-05 15:21:25 +00:00
- Removal of a previously shared group with a project
2020-02-20 18:08:51 +00:00
- LFS enabled or disabled
2019-05-05 15:21:25 +00:00
- Shared runners minutes limit changed
2020-02-20 18:08:51 +00:00
- Membership lock enabled or disabled
- Request access enabled or disabled
- 2FA enforcement or grace period changed
2019-05-05 15:21:25 +00:00
- Roles allowed to create project changed
2019-11-15 03:06:34 +00:00
Group events can also be accessed via the [Group Audit Events API ](../api/audit_events.md#group-audit-events-starter )
2019-07-08 08:50:38 +00:00
### Project events **(STARTER)**
2019-05-05 15:21:25 +00:00
NOTE: **Note:**
2020-04-21 15:21:10 +00:00
You need Maintainer [permissions ](../user/permissions.md ) or higher to view the project Audit Events page.
2019-05-05 15:21:25 +00:00
To view a project's audit events, navigate to **Project > Settings > Audit Events** .
From there, you can see the following actions:
2020-02-20 18:08:51 +00:00
- Added or removed deploy keys
- 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)
2019-05-05 15:21:25 +00:00
2019-07-08 08:50:38 +00:00
### Instance events **(PREMIUM ONLY)**
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
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 admin log, visit **Admin Area > Monitoring > Audit Log** .
In addition to the group and project events, the following user actions are also
recorded:
- Failed Logins
2020-02-20 18:08:51 +00:00
- Sign-in events and the authentication type (such as standard, LDAP, or OmniAuth)
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)
- 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)
2019-05-05 15:21:25 +00:00
2020-02-20 18:08:51 +00:00
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
2019-05-05 15:21:25 +00:00
(for authentication events).
2019-07-09 13:25:58 +00:00
![audit log ](img/audit_log.png )
2019-05-05 15:21:25 +00:00
2019-11-15 03:06:34 +00:00
Instance events can also be accessed via the [Instance Audit Events API ](../api/audit_events.md#instance-audit-events-premium-only )
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 )
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-02-20 18:08:51 +00:00
It may make the user interface for your project or audit logs very busy, and the disk space consumed by the
2020-03-24 03:09:28 +00:00
`audit_events` PostgreSQL table will 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.
In an upcoming release, Audit Logs for Git push events will be enabled
2020-05-21 06:08:25 +00:00
by default. Follow [#7865 ](https://gitlab.com/gitlab-org/gitlab/-/issues/7865 ) for updates.
2019-09-23 18:06:14 +00:00
If you still wish to enable **Repository push** events in your instance, follow
the steps bellow.
**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)
```