Go to Application

Audit logs

18 days ago · 17 min read

Cloud

Contribute

CircleCI logs important events in the system for audit and forensic analysis purposes. Audit logs are separate from system logs that track performance and network metrics. CircleCI offers functionalities to request and stream audit logs.

Request audit logs

All CircleCI organizations can request audit logs. You need to be an organization admin to access the Request audit logs feature from the CircleCI web app.

How to request audit logs

Navigate to Organization Settings Security.
Scroll down to the Audit Logs section.
Select the date range and then select Request audit logs.

The earliest start date is one year ago from the current day, and the latest end date is the current day. The data available will depend on the data retention period set per organization, so the returned time period for the data could be less than the requested time frame.

In some situations, the internal system may generate duplicate events in the audit logs. The id field of the downloaded logs is unique per event and can be used to identify duplicate entries.

Audit logs can be retrieved for up to 12 months. See our data retention policy.

Submitted dates are in UTC. To avoid issues arising from potential time zone differences, CircleCI adds extra time to the request. For example, if you request August 2 - August 5, the returned results will be in the range August 1 - August 6. The audit log request column is also displayed in UTC.

Request status

In the CircleCI web app, a status will show the following information:

Time frame requested.
User who made the request.
Date request was made.
Expiry date of the request.
Request status.

Statuses are updated once per hour on the 30-minute mark (for example, 09:30, 10:30, 11:30).

Successful requests can be either of the following:

Active with a download link.
Active without any data (no download link).
Expired (no longer available to download).

Once your request is successfully processed, select Download logs to download the audit log as a CSV file. Successful requests are available to download for 30 days.

Audit log fields with nested data contain JSON blobs.

Frequency limits

Frequency limits for requests are as follows:

Free Plan: 1 request per day
All paid plans: 3 requests per day
Maximum query window for 30 days - specifically, a customer can request logs for any 30 day window where the start of the window is within the last calendar year

If your organization has reached the maximum amount of requests per 30 days, the audit log request feature will be disabled.

If you hover over the disabled Request audit logs button, a tooltip will appear displaying the date when new requests can be made. Pending requests count toward the rate limit.

Stream audit logs

If you choose to set up audit log streaming, you can still request audit logs.

Set up audit log streaming direct to your own AWS S3 bucket.

Audit log streaming provides the following benefits to your organization:

Maintain comprehensive security visibility.
Meet compliance requirements.
Integrate CircleCI audit data with your existing security monitoring infrastructure.

Set up audit log streaming

Before setting up audit log streaming, ensure you have the following:

CircleCI Scale Plan (the feature is not available to Free or Performance customers)
AWS account with permissions to create and manage S3 buckets
IAM role or user with appropriate S3 write permissions
Network configuration to allow secure connections between CircleCI and AWS

The following steps guide you through setting up your S3 bucket, AWS authentication, audit log configuration, and verification.

1. Implement AWS prerequisites

The following steps describe how to set up AWS prerequisites:

Create an S3 bucket in your AWS account to store the audit logs.

You can also specify an optional folder or prefix (for example, my-bucket/audit-logs).

Take note of the AWS region where you created the S3 bucket (for example,us-east-1).

Create an IAM role that CircleCI can assume. This role requires two key policies:

Trust policy

This policy allows CircleCI’s service to assume the role. The principal ARN in this policy is a template that you must configure with your specific AWS account and CircleCI organization IDs.

The complete template for the trust relationship is the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/oidc.circleci.com/org/<org-id>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.circleci.com/org/<org-id>:aud": "<org-id>",
                    "oidc.circleci.com/org/<org-id>:sub": "org/<org-id>/file-streaming/audit-logs"
                }
            }
        }
    ]
}

Replace <aws-account-id> with your 12-digit AWS account ID and <org-id> with your unique CircleCI organization ID (found on the Organization Settings Overview page in the CircleCI web app).

Permissions policy

This policy grants the role permission to write objects to your S3 bucket (and any specified prefix).

The minimum required access policy for the role is as follows:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket-name>/*"
            ]
        }
    ]
}

Replace <bucket-name> with the name of your S3 bucket.

Set up an OIDC Identity Provider to allow CircleCI’s OIDC tokens to be used for authentication.
1. Navigate to the IAM Console in AWS.
2. In the left navigation menu, select Identity Providers.
3. Select Add provider.
4. Choose OpenID Connect as the provider type.
5. In the Provider URL field, specify https://oidc.circleci.com/org/<org-id> (replace <org-id> with your CircleCI organization ID).
6. In the Audience field, enter your organization ID.

2. Configure audit log streaming

Go to the CircleCI web app.
Navigate to Organization Settings Security.
Scroll down to the Audit Logs Streaming audit logs section and select Stream audit logs.
Confirm that you have completed the prerequisites by selecting Continue.
In the configuration dialog, specify the following fields:
1. Region: The AWS region where your S3 bucket is located.
2. S3 Bucket Name: The name of the S3 bucket where audit logs will be streamed.
3. Role ARN: The Amazon Resource Name (ARN) for the IAM role that CircleCI will use to access your S3 bucket.
Select Connect CircleCI to AWS.
When the connection to your S3 bucket is successfully validated, Connected appears under Status.

Creating a streaming configuration pushes an empty file named circleci_connectivity_test_<timestamp> to the configured bucket. This verifies that the system has sufficient permissions to start the stream.

3. Verify and test

After setting up audit log streaming follow these steps to validate the setup was successful:

Verify successful streaming by checking the Last delivery timestamp.
Confirm logs are appearing in your designated S3 bucket.
Test integrations with your Security Information and Event Management (SIEM) solution or security monitoring tools.
Set up appropriate alerts for connection failures or delivery interruptions.

Stream to S3-compatible storage

Select Other S3-compatible service in the streaming dialog to connect to an S3-compatible endpoint such as MinIO.

The setup steps vary by provider. At a high level you will:

1. Prepare your S3-compatible destination

Create a bucket for audit logs in your S3-compatible service.
Create or identify a role/principal that CircleCI can assume using OIDC. The exact process and identifier format depend on your provider. Examples include an AWS-style ARN (for example, arn:aws:iam::…:role/…) or a provider-specific role identifier (for example, MinIO arn:minio:iam:::role/…).

Grant the role/principal permission to write objects to your bucket (minimum required: s3:PutObject on <your-bucket>/*). For example:

// minio S3 example policy
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject"
      ],
      "Resource": [
        "arn:minio:s3:::<bucket-name>/*"
      ]
    }
  ]
}

2. Authentication and authorization considerations

Key OIDC configuration details:

When setting up the OIDC Identity Provider to trust CircleCI, use these parameters:

OpenID Configuration URL (Issuer URL): https://oidc.circleci.com/org/<ORG_ID>/.well-known/openid-configuration
(Remember to substitute your actual CircleCI Organization ID.)
OpenID Client ID (Audience): Your CircleCI Organization ID (the <ORG_ID> value).
Scope: Use the standard required scope: openid.

Validation and network requirements:

Server Endpoint Connectivity: The AWS S3 compatible server, acting as the token validator, must be able to reach the CircleCI OIDC Provider endpoint to fetch the public keys required to validate the token’s cryptographic signature.
Provider Validation: Your OIDC provider configuration must be set up to accept and successfully validate CircleCI’s OIDC tokens for the configured role or principal you intend to grant access to within your storage solution.

Ensure your AWS S3 compatible server’s network configuration allows necessary outgoing connections to the internet, specifically to oidc.circleci.com, for token validation to succeed.

3. Configure CircleCI to stream to your S3-compatible service

Go to the CircleCI web app and navigate to Organization Settings Security.
In Audit Logs Streaming audit logs, select Stream audit logs.
Choose Other S3-compatible service.
Confirm that you have completed the prerequisites by selecting Continue.
Fill out the fields as follows:
1. Region: Optional. Many S3-compatible providers default to us-east-1 if not set.
2. S3 Bucket Name: The exact name of the bucket you created.
3. Role ARN: The role identifier recognized by your provider (for example, a provider-specific role ID/ARN).
4. Endpoint: The HTTPS endpoint of your S3-compatible API (for example, https://s3.<region>.<provider-domain>; or your custom host and port).
The configuration form appears as follows:
Select Connect CircleCI to S3-compatible service.

When the connection is validated, the Status will show passed icon Connected. Creating a streaming configuration pushes an empty file named circleci_connectivity_test_<timestamp> to the configured bucket to verify permissions.

Manage active streams

Once configured, you can view and manage audit log streams. The following options are available to you in the CircleCI web app:

Pause streaming: Use the toggle switch under Actions to temporarily disable log streaming. Status will change to Disabled.
Monitor delivery: Check the Last delivery field to verify recent successful deliveries.
Delete configuration: Select the trash icon under Actions to remove the streaming setup. In the popup warning, select Delete to confirm.
Restart streaming: Toggle the switch to resume paused streams.

Limitations

Audit log streaming is only available to CircleCI Scale Plan customers. Free and Performance Plan customers do not have access to this feature.
Currently, streaming is supported for a single S3 bucket per organization.

Troubleshooting

Configuration Issues: Most problems are related to AWS IAM permissions or S3 bucket configuration.
Connection Failures: If Status shows Disconnected, verify AWS credentials and permissions before contacting support. Use the toggle switch to restart streaming once issues are resolved.
Missing Logs: Ensure that your S3 bucket policies allow write access from CircleCI’s service accounts.

Audit log events

The following list shows common and important events found in the audit log. This list is not comprehensive, and you may see additional action types logged that are not represented below. See action in the Field section below for the definition and format.

ams.invitation.accepted
ams.invitation.created
ams.invitation.revoked
audit_log.download_url.generated
audit_log.requested
build.create
checkout-key.create
checkout-key.delete
checkout-key.delete-all
component.cancel_release
component.promote_release
context.create
context.delete
context.env_var.delete
context.env_var.store
context.group_add
context.group_remove
context.restriction.create
context.restriction.delete
context.secrets.accessed
deploy-keys.delete
group.delete
group.update
group_member.add
group_member.remove
orb.namespace.create
orb.orb.create
orb.publish.dev
orb.publish.release
orb.version.promote
org.contacts.updated
org.create
org.rename
org.workflows.deleted
org_member.remove
organization.settings.update
project.add
project.api_token.create
project.create
project.delete
project.env_var.copy
project.env_var.create
project.env_var.delete
project.follow
project.rollback
project.settings.update
project.setup
project.ssh_key.create
project.ssh_key.delete
project.stop_building
project.toggle-abusive
project.unfollow
project_group_role_grant.create
project_group_role_grant-update
release_integration-create
release_integration-delete
release_integration-token-create
release_integration-token-revoke
role_grant-delete
role_grant-update
schedule-create
schedule-delete
schedule-update
trigger-create
trigger-delete
trigger_event-create
webhook-create
webhook-delete
webhook-update
workflow-cancel
workflow-job-context-request
workflow-job-finish
workflow-job-scheduled
workflow-job-start
workflow-retry
workflow-schedule-start
workflow-start

Audit log fields

Field Description

Field	Description
`action`	The action taken that created the event. The format is ASCII lowercase words, separated by dots, with the entity acted upon first and the action taken last. In some cases entities are nested, for example, `workflow.job.start`.
`actor`	The actor who performed this event. In most cases this will be a CircleCI user. This data is a JSON blob that will always contain `id` and `type` and will likely contain `name`.
`target`	The entity instance acted upon for this event, for example, a project, an org, an account, or a build. This data is a JSON blob that will always contain `id` and `type` and will likely contain `name`.
`payload`	A JSON blob of action-specific information. The schema of the payload is expected to be consistent for all events with the same `action` and `version`.
`occurred_at`	When the event occurred in UTC expressed in ISO-8601 format with up to nine digits of fractional precision, for example '2017-12-21T13:50:54.474Z'.
`metadata`	A set of key/value pairs that can be attached to any event. All keys and values are strings. This can be used to add additional information to certain types of events.
`id`	A UUID that uniquely identifies this event. This is intended to allow consumers of events to identify duplicate deliveries.
`version`	Version of the event schema. Currently the value will always be 1. Later versions may have different values to accommodate schema changes.
`scope`	If the target is owned by an Account in the CircleCI domain model, the account field should be filled in with the Account name and ID. This data is a JSON blob that will always contain `id` and `type` and will likely contain `name`.
`success`	A flag to indicate if the action was successful.
`request`	If this event was triggered by an external request, this data will be populated and may be used to connect events that originate from the same external request. The format is a JSON blob containing `id` (the unique ID assigned to this request by CircleCI).

action

The action taken that created the event. The format is ASCII lowercase words, separated by dots, with the entity acted upon first and the action taken last. In some cases entities are nested, for example, workflow.job.start.

actor

The actor who performed this event. In most cases this will be a CircleCI user. This data is a JSON blob that will always contain id and type and will likely contain name.

target

The entity instance acted upon for this event, for example, a project, an org, an account, or a build. This data is a JSON blob that will always contain id and type and will likely contain name.

payload

A JSON blob of action-specific information. The schema of the payload is expected to be consistent for all events with the same action and version.

occurred_at

When the event occurred in UTC expressed in ISO-8601 format with up to nine digits of fractional precision, for example '2017-12-21T13:50:54.474Z'.

metadata

A set of key/value pairs that can be attached to any event. All keys and values are strings. This can be used to add additional information to certain types of events.

id

A UUID that uniquely identifies this event. This is intended to allow consumers of events to identify duplicate deliveries.

version

Version of the event schema. Currently the value will always be 1. Later versions may have different values to accommodate schema changes.

scope

If the target is owned by an Account in the CircleCI domain model, the account field should be filled in with the Account name and ID. This data is a JSON blob that will always contain id and type and will likely contain name.

success

A flag to indicate if the action was successful.

request

If this event was triggered by an external request, this data will be populated and may be used to connect events that originate from the same external request. The format is a JSON blob containing id (the unique ID assigned to this request by CircleCI).

[path]

[title]

Audit logs

Request audit logs

How to request audit logs

Request status

Frequency limits

Stream audit logs

Set up audit log streaming

1. Implement AWS prerequisites

2. Configure audit log streaming

3. Verify and test

Stream to S3-compatible storage

1. Prepare your S3-compatible destination

2. Authentication and authorization considerations

3. Configure CircleCI to stream to your S3-compatible service

Manage active streams

Limitations

Troubleshooting

Audit log events

Audit log fields