Audit AI events

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

This feature is in beta. It is subject to change without notice. For more information, see GitLab Testing Agreement.

Use the AI audit event report for a unified, browsable record of GitLab Duo agent activity. Each agent session produces a comprehensive audit artifact that you can inspect.

AI audit events are generated by the AI Gateway.

  • On GitLab.com, agent sessions are routed through the GitLab-managed AI Gateway, which forwards AI audit events to GitLab.com.
  • On GitLab Self-Managed, agent sessions can be routed through the GitLab-managed AI Gateway or through a self-hosted AI Gateway. If you’re using your own AI Gateway, configure it to forward AI audit events to your GitLab instance. Otherwise, no events are recorded in the dashboard. To forward events, set the AIGW_AUDIT_EVENT__ENABLED environment variable to true on the AI Gateway.

GitLab records tool calls made by MCP clients to the GitLab MCP server itself, without the AI Gateway. For more information, see audit events for the GitLab MCP server.

View AI audit events

AI audit events are available on the Governance page as the Audit events tab.

Prerequisites:

  • You have the Owner or Security Manager role for the top-level group or project, or a custom role with the read_agent_artifacts permission. Without it, the Audit events tab shows a message instead of the events.

To view AI audit events for a group:

  1. In the top bar, select Search or go to and find your top-level group.
  2. In the left sidebar, select AI > Governance.
  3. Select the Audit events tab.

The tab displays a list of agent sessions. Each row shows:

  • The agent type (workflow definition).
  • The project the session ran in.
  • The number of audit events in the session.
  • The session start time.

Filter sessions

You can filter the session list to narrow results:

  • Project: Filter by project path, or exclude a specific project.
  • Date range: Filter sessions created after or before a specific date.
  • Triggered by: Filter by the user who triggered the session, or exclude a specific user.
  • Flow type: Filter by flow type, or exclude a specific flow type.

View session details

To inspect the events within a session:

  1. Select a session row to open the session details panel. The panel shows session metadata and a chronological list of audit events.
  2. Select an individual event to view its full details, including entity and target information.

Some flows, such as business logic scanning, keep only metadata about their sessions. For these flows, audit events record metadata like status, timing, model, and tool names, but no prompts, responses, or tool content.

Enable AI audit event storage

AI audit event storage is disabled by default. You must explicitly enable storage before agent session data is written to the database or ClickHouse, or to the audit_json.log file. Disabling storage does not affect real-time streaming of AI audit events.

The setting cascades from instance to group to project:

  • When disabled and locked at the group level, projects in that group cannot override it.
  • When enabled and locked at the group level, all projects in that group have storage enabled and cannot disable it.

Prerequisites:

  • You must have the Owner role or the Security Manager role for the group or project.

Enable storage for a group

  1. In the top bar, select Search or go to and find your group.
  2. Select Settings > GitLab Duo.
  3. Select Change configuration.
  4. In the Data and privacy section, select Store AI audit events.
  5. Select Save changes.
  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > General.
  3. Expand the GitLab Duo section.
  4. In the Data and privacy section, select Store AI audit events.
  5. Select Save changes.

Enable storage for a project

  1. In the top bar, select Search or go to and find your project.
  2. Select Settings > General.
  3. Expand the GitLab Duo section.
  4. Turn on the Store AI audit events toggle.
  5. Select Save changes.

If the setting is locked by a parent group, the control is disabled and cannot be changed at the project level.

Audit events for the GitLab MCP server

  • Status: Beta

The availability of this feature is controlled by a feature flag. For more information, see the history.

GitLab records an AI audit event for each tool call that an MCP client makes to the GitLab MCP server. Use these events to see what external agents, such as Claude Code, Cursor, and Codex, do in GitLab. The server records the events, so you don’t need to add tracking to the client.

Prerequisites:

  • For events to appear in the Audit events tab, AI audit event storage must be turned on for the group or project that receives them.

Recorded events

Event Recorded when
ai_agent_session_started A client makes its first call in a new session.
ai_tool_invoked A client calls a tool, including calls that fail or that a tool governance rule blocks.
ai_tool_execution_failed A tool call fails, including calls that Always Deny blocks. A failed call records this event and ai_tool_invoked.
ai_agent_session_ended A session closes.

How calls are grouped into sessions

The MCP protocol has no session identifier, so GitLab infers sessions. Calls belong to the same session when they come from the same user, through the same OAuth application, and target the same project or group.

A session:

  • Ends after 15 minutes without a call.
  • Lasts at most 30 minutes. If the client keeps making calls, GitLab starts a new session.

A scheduled job that runs every five minutes closes sessions that have ended. GitLab records the time the session expired as its end time, not the time the job ran.

Because GitLab infers sessions, one session might not match one conversation in your client.

Which group receives the events

GitLab records each event for the project or group that the tool call names in its arguments, for example in project_id. This choice decides which group’s AI audit events and event streams receive the event.

  • If the user has the Guest, Planner, Reporter, Security Manager, Developer, Maintainer, or Owner role in that project or group, GitLab records the event there. Instance administrators and organization owners count as members.
  • Otherwise, GitLab records the event in the user’s default GitLab Duo namespace, or in their personal namespace if they have no default. This also applies to calls that don’t name a project or group. The owners of the project or group that the call targeted don’t see these events.

Event details

Each event has the following fields in its details object, unless noted. Session events don’t include the tool, outcome, error, and argument fields. The ai_agent_session_ended event also omits the OAuth application, via, and token_id fields, because a scheduled job records it outside any client request.

Field Description
mcp_server Always core, which identifies the GitLab MCP server.
agent_initiated Always true.
agent_name The agent, based on the name of the OAuth application: claude-code, opencode, cursor, codex, or unknown. Calls that don’t use an OAuth application, such as calls authenticated with a personal access token, are unknown. GitLab does not verify the application name that a client declares, so use this field for attribution only, not for authorization.
oauth_application_id and oauth_application_name The OAuth application the client used, with the name exactly as stored. Omitted for calls authenticated with a personal access token.
tool_name The tool the client called.
dispatched_tool_name The tool that the called tool routed the call to. For example, save_merge_request can route to update_merge_request. Omitted when the tool does not route.
outcome success or error.
failure_reason Why a call failed. For example, unauthorized for a call that a tool governance rule blocked. Omitted for successful calls.
duration_s How long the call took, in seconds.
error_class and error_message The error for a failed call. GitLab truncates the message to 255 characters.
arguments The arguments the client sent. GitLab replaces sensitive values, such as tokens, with [FILTERED]. If the arguments are larger than 10 KB, GitLab replaces them with a note that they were omitted.
via and token_id via is duo_agent_platform when the call used a token issued to GitLab Duo Agent Platform, and token_id is the ID of that token. These calls can also appear in events from GitLab Duo Agent Platform, so you can use these fields to match them.

View MCP server sessions

Prerequisites:

  • You have the Owner role for the top-level group.

To view MCP server sessions:

  1. In the top bar, select Search or go to and find your top-level group.
  2. In the left sidebar, select AI > Governance.
  3. Select the Audit events tab.
  4. Select a session to open the session details panel.

MCP server sessions appear with the sessions from other agents. In the AI Item column and in the session details panel, GitLab shows the name of the client when it recognizes the agent. Otherwise, GitLab shows GitLab MCP server.

Event attribution with composite identity

When an agent session runs with a composite identity, which is the default identity for agent sessions, the AI audit events for the session are attributed to the service account. The author_id field contains the user ID of the service account, and the service account appears as the event author.

The event details field records the human user who started the session:

Field Description
human_author_id User ID of the human user
human_author_name Name of the human user
human_author_username Username of the human user

When a session is authenticated with a human user’s own token, the human user is the event author and the human_author_* fields are not added.