Before touching architecture or setup, it helps to understand exactly what is being moved, and why GitHub built a dedicated feature for it instead of just letting people download a report.

The audit log itself

Every GitHub Enterprise account keeps an audit log: a running record of security-relevant and administrative actions taken across the enterprise. This includes things like a user being added to a team, a repository’s visibility changing from private to public, a personal access token being created, a branch protection rule being removed, or an organization owner changing billing settings. Each entry records who did it, what they did, when, and often from where.

Alongside the audit log, GitHub also tracks Git events — the raw plumbing-level actions of the Git protocol itself, such as clones, fetches, and pushes. These are far higher in volume than administrative audit events, which is why GitHub treats them as a related but separate stream of data.

Why “streaming” instead of just “viewing”

GitHub already lets administrators view the audit log inside the web interface, and lets them query it through search syntax or the REST API. That works fine for looking something up after the fact. But it has three built-in limits: the UI only shows a few months of history, Git events are not shown in the UI at all because of their volume, and manually pulling data through the API does not scale to a security team that wants to watch for suspicious activity continuously.

Audit log streaming solves all three problems at once. Once configured, GitHub pushes a continuous, near real-time copy of audit and Git events to an external destination the organization controls — an Amazon S3 bucket, a Splunk instance, a Datadog account, and so on. From that point on, the organization owns the data, can keep it for as long as it wants, and can run whatever analysis, alerting, or long-term archival process fits its own compliance program.

Streaming is not a convenience feature; for many regulated organizations it is close to a compliance requirement. Understanding the underlying motivations makes every later design decision easier to follow.

Retention beyond GitHub’s own limits

Many industries — finance, healthcare, government contracting — are legally required to retain security-relevant logs for years, not months. GitHub’s own storage was never designed to be that permanent archive; streaming is the sanctioned way to build one, in a system the organization already trusts and already pays for.

A single pane of glass for security

Most security teams do not want to check five different systems for suspicious activity. They already have a SIEM (Security Information and Event Management) tool — Splunk and Datadog are two of the most common — where logs from firewalls, cloud infrastructure, and identity providers already converge. Streaming lets GitHub’s audit trail join that same pane of glass instead of living on an island.

Forensics and incident response

When something does go wrong — a leaked token, a suspicious permission change, a repository made public by mistake — investigators need a timeline that reaches back further than a few months and that cannot be quietly altered from inside GitHub itself. An external, append-only copy of the audit log gives investigators exactly that kind of independent, tamper-resistant record.

Zooming out, audit log streaming is a pipeline with four moving parts: the event source, GitHub’s streaming service, the encrypted credential handshake, and the destination.

You may likeWhat Is a Reusable Workflow?→

flowchart LR
    A[GitHub Enterprise actions] --> B[Audit & Git events generated]
    B --> C[GitHub streaming service]
    C -->|encrypted, batched| D{Configured destination}
    D --> E[Amazon S3]
    D --> F[Azure Blob Storage / Event Hubs]
    D --> G[Splunk / HTTPS Event Collector]
    D --> H[Datadog]
    D --> I[Google Cloud Storage]
        

Enterprise-scoped, not organization-scoped

A common early misunderstanding is expecting to configure streaming per organization. In reality, the stream is set up once at the enterprise account level and automatically covers every organization nested inside that enterprise, along with enterprise-level events like billing and owner changes.

Understanding the internal mechanics — how credentials are protected, how files are named, and how delivery is guaranteed — explains almost every operational quirk you will encounter later.

The sealed-box credential exchange

GitHub never wants to store an organization’s long-lived cloud secret (an AWS access key, an Azure SAS token, a Splunk HEC token) in a way that a compromised database could expose in plain text. To avoid that, GitHub publishes a public encryption key specific to the enterprise. Before sending credentials, the administrator’s tooling encrypts them locally against that public key — a technique often called a “sealed box.” Only GitHub’s private key, held internally, can unseal that value, and it does so only at the moment it needs to authenticate to the destination.

Batching and file format

Events are not streamed one at a time as individual network calls; that would be wasteful and slow. Instead, GitHub groups events into small batches and writes them as compressed JSON files. For storage-style destinations such as Amazon S3, files are typically organized in a predictable, time-partitioned folder structure, so a security tool — or a human — can quickly locate the events for a specific hour without scanning the entire bucket.

At-least-once delivery

GitHub’s streaming pipeline guarantees that an event will be delivered at least once. In distributed systems, this is a deliberate and common trade-off: guaranteeing “exactly once” delivery across an unreliable network is extremely expensive, while “at least once” is far simpler and only occasionally produces a duplicate. GitHub embeds a unique event identifier in every record specifically so that downstream tools can deduplicate if they need a perfectly clean dataset.

sequenceDiagram
    participant Owner as Enterprise Owner
    participant GH as GitHub
    participant Dest as Destination (e.g. S3)
    Owner->>GH: Request stream public key
    GH-->>Owner: Return encryption key
    Owner->>GH: Submit sealed (encrypted) credentials
    GH->>GH: Store sealed credentials only
    loop Continuous operation
        GH->>GH: Batch new audit/Git events
        GH->>Dest: Push encrypted batch (at-least-once)
        Dest-->>GH: Acknowledge receipt
    end
    GH->>GH: Run health check every 24 hours
        

GitHub does not force organizations onto a single vendor. Instead it supports the handful of destinations that already dominate log storage and security analytics.

Choosing between object storage and a SIEM

Object storage destinations like S3, GCS, and Azure Blob Storage are best thought of as a durable, low-cost archive: cheap to keep for years, but not built for live searching without adding another tool on top (which is exactly what the earlier search result about routing S3-stored GitHub audit data into AWS CloudTrail Lake demonstrates — the bucket becomes raw material for a proper analysis layer). SIEM destinations like Splunk and Datadog, on the other hand, are built for immediate searching, dashboards, and alerting, at a higher per-gigabyte cost. Many mature organizations use both together: a SIEM for the most recent, actively monitored window, and object storage as the long-term, low-cost archive behind it.

The exact fields differ slightly per destination, but the overall setup flow follows the same shape every time.

Not every action inside GitHub is treated the same way once it reaches the stream. Splitting events into categories makes filtering and cost management much easier.

Because Git events are high-volume plumbing data rather than security-decision data, most streaming setups apply some form of filtering so the destination is not flooded with routine clone traffic when the security team only cares about administrative changes. Filters are typically expressed as patterns against the event’s category — for example, capturing every repo.* or business.* event while leaving out the noisiest categories.

A feature whose entire purpose is security cannot itself be a weak point — GitHub’s design choices reflect that directly.

Least-privilege credentials

Every destination integration is designed around the principle of granting GitHub only the narrow permission it actually needs — typically “write object” and nothing else. An access policy that only allows writing new objects into a single named bucket cannot be used to read, modify, or delete anything else in the account, which limits the blast radius if that specific credential were ever exposed.

Short-lived credentials where possible

For Amazon S3 specifically, GitHub supports an OIDC-based authentication flow as an alternative to a permanent access key. Instead of a secret that lives forever until someone manually rotates it, GitHub exchanges short-lived tokens for each session, which meaningfully shrinks the window during which a leaked credential would even be useful to an attacker.

Data in transit and at rest

Credentials are encrypted end-to-end during setup using the sealed-box method described earlier, and the events themselves are transmitted over encrypted connections to the destination. Once the data lands in the destination, its ongoing protection — encryption at rest, access control on the bucket or index — becomes the organization’s own responsibility, just like any other data it stores.

A stream that silently stops working is arguably worse than no stream at all, because it creates false confidence. GitHub builds several safeguards around this exact risk.

Automatic health checks

GitHub runs a health check against every configured stream roughly once every 24 hours. If the destination cannot be reached, or if authentication fails, the enterprise owners are notified by email so the problem can be fixed before too much data is lost.

Pausing without losing data

Sometimes a destination needs planned maintenance — rotating a credential, resizing a bucket policy, migrating to a new Splunk cluster. GitHub allows a stream to be paused for up to seven days without losing any events, because that matches the retention window for the underlying Git event data. Anything paused longer than that risks losing Git events that rolled off before the stream resumed.

Watching for silent drift

Beyond GitHub’s own health checks, mature operations teams add their own monitoring on the destination side — for example, an alert if no new files have landed in the S3 bucket for several hours, independent of whatever GitHub itself reports. Two independent checks catch failures that a single check might miss.

No feature is free of costs. Weighing both sides honestly helps a team decide how aggressively to adopt streaming and how much tooling to build around it.

11Best Practices and Common Mistakes

You may likeWhat Is Git Bisect?→

Most incidents involving audit log streaming come from a handful of repeatable mistakes — and a handful of repeatable fixes.

Seeing how streaming fits into a broader toolchain makes the abstract architecture from earlier chapters concrete.

Audit log streaming is an Enterprise-tier capability, configured by an enterprise owner. It is not available for individual repositories or standalone free/team-tier organizations.

Yes. GitHub supports configuring multiple concurrent streams across its supported destinations, which lets one team route data to a SIEM for live monitoring while another team routes the same data to cold storage for archival.

No. Streaming only captures events generated after the stream is enabled — there is no retroactive export of historical activity.

A stream can be paused, or may fail silently, for up to about seven days without losing Git event data, since that matches GitHub’s internal retention window for those events. Beyond that window, unrecovered Git events may be gone permanently; audit events have a longer internal buffer.

Yes. GitHub’s delivery guarantee is “at least once,” which occasionally produces duplicates during retries. Downstream systems should deduplicate using the event’s unique identifier if exact counts matter.

No, it runs alongside it. The in-product view remains available for quick lookups; streaming is the mechanism for long-term retention and integration with external tools.

Audit log streaming takes GitHub’s internal record of security-relevant and Git-level activity and continuously exports it, in near real time, to a destination the organization already trusts — Amazon S3, Google Cloud Storage, Azure Blob Storage, Azure Event Hubs, Splunk, or Datadog. It exists because GitHub’s own built-in retention is deliberately short, because Git events are not even visible in the product UI, and because most security teams need this data alongside everything else already flowing into their SIEM. The design leans heavily on least-privilege, encrypted credentials and an honest “at least once” delivery guarantee, and it rewards teams that plan retention, deduplication, and access control from day one rather than reacting after an incident.