Audit Logs

Audit logs provide a comprehensive, queryable record of all actions taken within your Ona organization. Track who performed an operation, on which resource, and when—enabling security monitoring, compliance reporting, and operational troubleshooting.

This feature is only available on the Enterprise tier. Contact sales to learn more.

What Are Audit Logs?

Audit logs capture a complete trail of activities within your organization:

Resource lifecycle: Creation, modification, and deletion of environments, projects, and runners
Configuration changes: Updates to organization settings, policies, and integrations
Security events: Token management, SSO configuration, and secret operations
Access control: Group and role modifications
Workflow activities: Task executions, service deployments, and automation runs

Audit Log Entry Structure

Each entry contains:

Actor: Who performed the action (user, service account, runner, or system)
Subject: What resource was affected and its type
Action: The specific operation performed (e.g., “Environment created”, “changed status, phase”)
Timestamp: When the action occurred
Organization: Which organization the action belongs to

Access Requirements

Organization Admin role required. Only users with the Organization Admin role can view and query audit logs. Regular organization members cannot access audit logs, even for resources they own. This restriction ensures sensitive operational data remains available only to authorized administrators.

What Gets Logged

Ona automatically generates audit log entries for all create, update, and delete operations on these resource types:

Infrastructure
- Environments, Runners, Projects, Environment Classes
Execution & Automation
- Tasks, Task Executions, Services, Workflows, Workflow Executions, Workflow Execution Actions, Agents, Agent Executions
Security & Access
- Users, Service Accounts, Personal Access Tokens, Host Authentication Tokens, Secrets (project, user, and organization-level), SSO Configuration, Groups
Organization
- Organization Policies, Domain Verification, Custom Domains, Billing
Integrations & Development
- Integrations, Integration Definitions, Runner SCM/LLM Integrations, Organization LLM Integrations, Prebuilds, Snapshots, Prompts, User Preferences
Other
- Environment Usage Records, Project Environment Classes

Actor Types - Audit logs identify who performed actions:

PRINCIPAL_USER - Human users
PRINCIPAL_SERVICE_ACCOUNT - Service accounts
PRINCIPAL_RUNNER - Runner infrastructure
PRINCIPAL_ENVIRONMENT - Environment processes
PRINCIPAL_RUNNER_MANAGER - Runner management systems
PRINCIPAL_AGENT_EXECUTION - AI agent executions
PRINCIPAL_ACCOUNT - Account-level operations

Querying Audit Logs

Using the CLI

The gitpod CLI (pre-installed on all Ona environments) provides the simplest way to query audit logs. Basic usage:

# View recent entries (default: 100)
gitpod audit-logs

# Specify limit
gitpod audit-logs --limit=500

Filter by actor:

# By user ID
gitpod audit-logs --actor-id="d2c94c27-3b76-4a42-b88c-95a85e392c68"

# By actor type
gitpod audit-logs --actor-principal="user"
gitpod audit-logs --actor-principal="service_account"

Filter by subject:

# By resource ID
gitpod audit-logs --subject-id="01951d94-d6ac-7edf-9021-a044cfd1908f"

# By resource type
gitpod audit-logs --subject-type="environment"
gitpod audit-logs --subject-type="project"

Combine filters:

gitpod audit-logs --subject-type="environment" --actor-principal="user" --limit=500

Export formats:

# JSON
gitpod audit-logs --format=json --limit=1000 > audit-logs.json

# YAML
gitpod audit-logs --format=yaml --limit=1000 > audit-logs.yaml

Example output:

SUBJECT ID                           SUBJECT TYPE              ACTOR ID                             ACTOR PRINCIPAL    ACTION                                                    CREATED AT
01951d94-d6ac-7edf-9021-a044cfd1908f RESOURCE_TYPE_ENVIRONMENT 0193e2f2-d0b5-7d52-87eb-235deadaf625 PRINCIPAL_RUNNER   changed update_time, status, phase, last_running_session 2025-02-21T12:10:05Z
0194f5dd-01ca-75f4-a200-74381ed43f86 RESOURCE_TYPE_PROJECT     d2c94c27-3b76-4a42-b88c-95a85e392c68 PRINCIPAL_USER     Project created                                           2025-02-21T11:45:22Z

Using the API

For programmatic access and SIEM integration, use the REST API. Authentication:

export GITPOD_API_KEY="your-personal-access-token"

Basic request:

curl https://app.gitpod.io/api/gitpod.v1.EventService/ListAuditLogs \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"pagination": {"pageSize": 100}}'

Filter by actor:

curl https://app.gitpod.io/api/gitpod.v1.EventService/ListAuditLogs \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "filter": {
         "actorIds": ["d2c94c27-3b76-4a42-b88c-95a85e392c68"],
         "actorPrincipals": ["PRINCIPAL_USER"]
       },
       "pagination": {"pageSize": 100}
     }'

Filter by subject:

curl https://app.gitpod.io/api/gitpod.v1.EventService/ListAuditLogs \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "filter": {
         "subjectTypes": ["RESOURCE_TYPE_ENVIRONMENT", "RESOURCE_TYPE_PROJECT"]
       },
       "pagination": {"pageSize": 100}
     }'

Pagination:

# First request - save token
curl https://app.gitpod.io/api/gitpod.v1.EventService/ListAuditLogs \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"pagination": {"pageSize": 100}}' \
     | jq -r '.pagination.nextToken' > next_token.txt

# Subsequent request - use token
curl https://app.gitpod.io/api/gitpod.v1.EventService/ListAuditLogs \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d "{\"pagination\": {\"pageSize\": 100, \"token\": \"$(cat next_token.txt)\"}}"

Response format:

{
  "entries": [
    {
      "id": "01951d94-d6ac-7edf-9021-a044cfd1908f",
      "actorId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
      "actorPrincipal": "PRINCIPAL_USER",
      "subjectId": "0194f5dd-01ca-75f4-a200-74381ed43f86",
      "subjectType": "RESOURCE_TYPE_ENVIRONMENT",
      "action": "changed status, phase",
      "createdAt": "2025-02-21T12:10:05Z"
    }
  ],
  "pagination": {
    "nextToken": "eyJpZCI6IjAxOTUxZDk0LWQ2YWMtN2VkZi05MDIxLWEwNDRjZmQxOTA4ZiJ9"
  }
}

Real-Time Event Monitoring

For real-time notifications instead of historical queries, use the WatchEvents API. This streaming endpoint pushes events as they occur—ideal for dashboards, automation triggers, and live monitoring.

Key Differences

Feature	ListAuditLogs API	WatchEvents API
Purpose	Historical analysis	Real-time monitoring
Access	Organization Admins only	Users with read access to resources
Data	Full audit trail with actor info	Resource changes only
Format	Paginated queries	Streaming events
Use Case	Compliance, security review	Dashboards, automation

Using WatchEvents with Python

Install the official SDK:

pip install gitpod-sdk

The GITPOD_API_KEY environment variable should contain your Personal Access Token. You only receive events for resources you have read access to.

Watch organization events:

import os
from gitpod import Gitpod

client = Gitpod(bearer_token=os.environ.get("GITPOD_API_KEY"))

# Stream organization-wide events (projects, runners, environments)
for event in client.events.watch(organization=True):
    print(f"{event.operation} on {event.resource_type}: {event.resource_id}")

Watch environment-specific events:

# Stream events for a specific environment (includes tasks, services)
for event in client.events.watch(environment_id="01951d94-d6ac-7edf-9021-a044cfd1908f"):
    print(f"Environment event: {event.operation} on {event.resource_type}")

Async usage:

import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod(bearer_token=os.environ.get("GITPOD_API_KEY"))

async def watch_events():
    async for event in await client.events.watch(organization=True):
        print(f"{event.operation} on {event.resource_type}")

asyncio.run(watch_events())

Event Operations

RESOURCE_OPERATION_CREATE - Resource created
RESOURCE_OPERATION_UPDATE - Resource modified
RESOURCE_OPERATION_UPDATE_STATUS - Status changed only
RESOURCE_OPERATION_DELETE - Resource deleted

Using Other Languages

For languages without an official SDK, use gRPC/Connect-compatible clients: Endpoint: POST https://app.gitpod.io/api/gitpod.v1.EventService/WatchEvents Headers:

Content-Type: application/json
Accept: application/jsonl
Authorization: Bearer YOUR_API_KEY

Request body (organization scope):

{"organization": true}

Request body (environment scope):

{"environmentId": "01951d94-d6ac-7edf-9021-a044cfd1908f"}

See the WatchEvents API reference for details.

Common Use Cases

Security Monitoring

# Monitor secret operations
gitpod audit-logs --subject-type="secret" --subject-type="user_secret" --subject-type="organization_secret"

# Track SSO changes
gitpod audit-logs --subject-type="sso_config"

# Review token management
gitpod audit-logs --subject-type="personal_access_token"

Compliance Reporting

# Export user actions
gitpod audit-logs --actor-principal="user" --format=json --limit=10000 > user-actions.json

# Track group changes
gitpod audit-logs --subject-type="group" --format=json > group-changes.json

Troubleshooting

# Recent environment changes
gitpod audit-logs --subject-type="environment" --limit=500

# Project configuration updates
gitpod audit-logs --subject-type="project" --actor-principal="user" --limit=500

# Workflow execution history
gitpod audit-logs --subject-type="workflow_execution" --limit=500

Resource Lifecycle Tracking

# Runner lifecycle
gitpod audit-logs --subject-type="runner" --limit=500

# Environment creation/deletion patterns
gitpod audit-logs --subject-type="environment" --limit=1000

Best Practices

Regular Monitoring

Export audit logs periodically to external storage for long-term retention
Integrate with your SIEM for centralized security monitoring
Establish baseline patterns and investigate anomalies

Access Control

Grant Organization Admin role only to users who need audit log access
Use dedicated service accounts for automated log collection
Rotate Personal Access Tokens regularly

Filtering & Analysis

Prioritize monitoring security-sensitive resource types
Combine multiple filter criteria to narrow results
Export to JSON/YAML for integration with analysis tools

Limitations

Retention: Audit logs are retained according to your organization’s data retention policy
No time filtering: Cannot filter by date/time range. Logs return in reverse chronological order (most recent first).

Workaround: Export to JSON and filter with jq using the createdAt field:

gitpod audit-logs --format=json | jq 'map(select(.createdAt >= "2025-01-01"))'

Rate limits: API requests subject to standard rate limiting
Filter limits: Maximum 25 values per filter type per request
Pagination: Maximum 100 entries per page

Quickstart

Ona Environments

Ona Agents

Ona Guardrails

Deployment

Editors & IDEs

Organizations

Projects

Integrations

Source Control

Audit Logs

What Are Audit Logs?

Audit Log Entry Structure

Access Requirements

What Gets Logged

Querying Audit Logs

Using the CLI

Using the API

Real-Time Event Monitoring

Key Differences

Using WatchEvents with Python

Event Operations

Using Other Languages

Common Use Cases

Security Monitoring

Compliance Reporting

Troubleshooting

Resource Lifecycle Tracking

Best Practices

Limitations

Quickstart

Ona Environments

Ona Agents

Ona Guardrails

Deployment

Editors & IDEs

Organizations

Projects

Integrations

Source Control

​What Are Audit Logs?

​Audit Log Entry Structure

​Access Requirements

​What Gets Logged

​Querying Audit Logs

​Using the CLI

​Using the API

​Real-Time Event Monitoring

​Key Differences

​Using WatchEvents with Python

​Event Operations

​Using Other Languages

​Common Use Cases

​Security Monitoring

​Compliance Reporting

​Troubleshooting

​Resource Lifecycle Tracking

​Best Practices

​Limitations

What Are Audit Logs?

Audit Log Entry Structure

Access Requirements

What Gets Logged

Querying Audit Logs

Using the CLI

Using the API

Real-Time Event Monitoring

Key Differences

Using WatchEvents with Python

Event Operations

Using Other Languages

Common Use Cases

Security Monitoring

Compliance Reporting

Troubleshooting

Resource Lifecycle Tracking

Best Practices

Limitations