Audit logs

Audit logs provide a queryable record of all actions in your organization: who performed an operation, on which resource, and when. Use them for security monitoring, compliance reporting, and troubleshooting.

Available on the Enterprise plan. Contact sales to learn more.

Access requirements

Organization admins and members with the Audit Log Reader role can access audit logs. Regular members cannot access audit logs, even for resources they own.

Entry structure

Each entry contains:

Actor: Who (user, service account, runner, or system)
Subject: What resource and type
Action: Operation performed (e.g., “Environment created”)
Timestamp: When
Organization: Which org

What gets logged

All create, update, and delete operations on:

Category	Resources
Infrastructure	Environments, Runners, Projects, Environment Classes
Execution	Tasks, Services, Workflows, Agents, and their executions
Security	Users, Service Accounts, Tokens, Secrets, SSO Config, Groups, Login/Logout events
Organization	Policies, Domain Verification, Custom Domains, Billing
Integrations	SCM/LLM Integrations, Prebuilds, Snapshots, Prompts

Actor types:

Type	Description
`PRINCIPAL_USER`	Human users
`PRINCIPAL_SERVICE_ACCOUNT`	Service accounts
`PRINCIPAL_RUNNER`	Runner infrastructure
`PRINCIPAL_ENVIRONMENT`	Environment processes
`PRINCIPAL_RUNNER_MANAGER`	Runner management systems
`PRINCIPAL_ACCOUNT`	Account-level operations

Querying audit logs

CLI

The ona CLI (pre-installed in all environments) is the simplest way to query audit logs.

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

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

Filter by actor:

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

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

Filter by subject:

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

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

Filter by time range:

# Logs from a specific date onward
ona audit-logs --from="2025-01-01T00:00:00Z"

# Logs within a date range
ona audit-logs --from="2025-01-01T00:00:00Z" --to="2025-01-31T23:59:59Z"

Combine filters:

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

Export formats:

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

# YAML
ona 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

API

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

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. Use it 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

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

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
ona audit-logs --subject-type="secret" --subject-type="user_secret" --subject-type="organization_secret"

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

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

Compliance reporting

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

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

Troubleshooting

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

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

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

Resource lifecycle tracking

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

# Environment creation/deletion patterns
ona 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
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

​Access requirements

​Entry structure

​What gets logged

​Querying audit logs

​CLI

​API

​Real-time event monitoring

​Key differences

​WatchEvents with Python

​Event operations

​Other languages

​Common use cases

​Security monitoring

​Compliance reporting

​Troubleshooting

​Resource lifecycle tracking

​Best practices

​Limitations

Access requirements

Entry structure

What gets logged

Querying audit logs

CLI

API

Real-time event monitoring

Key differences

WatchEvents with Python

Event operations

Other languages

Common use cases

Security monitoring

Compliance reporting

Troubleshooting

Resource lifecycle tracking

Best practices

Limitations