Audit event schema and examples

Audit event schema

History
  • Documentation for an audit event streaming schema was introduced in GitLab 15.3.

Audit events have a predictable schema in the body of the response.

Field Description Notes Streaming Only Field
author_id User ID of the user who triggered the event   No
author_name Human-readable name of the author that triggered the event Helpful when the author no longer exists Yes
created_at Timestamp when event was triggered   No
details JSON object containing additional metadata Has no defined schema but often contains additional information about an event No
entity_id ID of the audit event’s entity   No
entity_path Full path of the entity affected by the auditable event   Yes
entity_type String representation of the type of entity Acceptable values include User, Group, and Key. This list is not exhaustive No
event_type String representation of the type of audit event   Yes
id Unique identifier for the audit event Can be used for deduplication if required No
ip_address IP address of the host used to trigger the event   Yes
target_details Additional details about the target   Yes
target_id ID of the audit event’s target   Yes
target_type String representation of the target’s type   Yes

Audit event JSON schema 

{
  "properties": {
    "id": {
      "type": "string"
    },
    "author_id": {
      "type": "integer"
    },
    "author_name": {
      "type": "string"
    },
    "details": {},
    "ip_address": {
      "type": "string"
    },
    "entity_id": {
      "type": "integer"
    },
    "entity_path": {
      "type": "string"
    },
    "entity_type": {
      "type": "string"
    },
    "event_type": {
      "type": "string"
    },
    "target_id": {
      "type": "integer"
    },
    "target_type": {
      "type": "string"
    },
    "target_details": {
      "type": "string"
    },
  },
  "type": "object"
}

Headers

History
  • X-Gitlab-Audit-Event-Type introduced in GitLab 15.0.

Headers are formatted as follows: 

POST /logs HTTP/1.1
Host: <DESTINATION_HOST>
Content-Type: application/x-www-form-urlencoded
X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN>
X-Gitlab-Audit-Event-Type: repository_git_operation

Example: audit event streaming on Git operations

Streaming audit events can be sent when authenticated users push, pull, or clone a project’s remote Git repositories:

  • Using SSH.
  • Using HTTP or HTTPS.
  • Using Download () in GitLab UI.

Audit events are not captured for users that are not signed in. For example, when downloading a public project.

Example: audit event payloads for Git over SSH events with deploy key

Fetch: 

{
  "id": "1",
  "author_id": -3,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "deploy-key-name",
    "author_class": "DeployKey",
    "target_id": 29,
    "target_type": "Project",
    "target_details": "example-project",
    "custom_message": {
      "protocol": "ssh",
      "action": "git-upload-pack"
    },
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "deploy-key-name",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-07-26T05:43:53.662Z",
  "target_type": "Project",
  "target_id": 29,
  "event_type": "repository_git_operation"
}