Help us learn about your current experience with the documentation. Take the survey.

Audit event schema and examples

Audit event schema

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
`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
`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
`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
`target_details`	Additional details about the target
`target_id`	ID of the audit event’s target
`target_type`	String representation of the target’s type

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"
}

When an audit event is related to the GitLab Duo Agent Platform, the details object includes a duo_related field set to true.

The following events can include this field:

Event type	Description
`application_setting_updated`	An application setting related to the GitLab Duo Agent Platform is updated.
`member_destroyed`	The membership of a GitLab Duo Agent Platform service account is removed.

Use this field to identify GitLab Duo Agent Platform activity in your Security Information and Event Management (SIEM) tool or other external tools, instead of service account naming patterns.

Headers

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",
      "written_bytes": 1048576,
      "received_bytes": 2048,
      "gl_key_type": "deploy_key",
      "gl_key_id": 24
    },
    "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"
}

The custom_message object includes data transfer size fields for Git operations:

written_bytes: Number of bytes sent to the client during the Git operation (for example, during a clone, fetch, or pull).
received_bytes: Number of bytes received from the client during the Git operation (for example, during a push).

These fields are omitted when no bytes are transferred, such as when a request fails before any data is exchanged.

The custom_message object includes key information for Git operations authenticated with an SSH key or deploy key:

gl_key_type: Type of the key used for authentication. Either key for user SSH keys, or deploy_key for deploy keys.
gl_key_id: ID of the key used for authentication.

These fields are omitted when the operation is not authenticated with a key, for example HTTP(S) with a username and password, or a deploy token.

Audit event schema and examples