Access, capture, and consume your audit logs
Whether you operate in a highly-regulated industry or not, audit logs are an essential way to keep track of the various activities taking place on GitHub Enterprise Cloud (GHEC). From configuration changes to API access to every push or pull of code, the audit logs provide detailed records at several structural levels, and it’s important to know how to access, capture, and interact with this data from the get-go.
In this guide, you will learn:
How to view your audit logs
What data is included in GHEC’s audit logs
How to configure your audit logs
How to stream and export audit logs for retention and analysis
What activities do audit logs include?
GitHub provides audit logs for a variety of activities in your enterprise and organizations, including:
Events from activities, like configuration changes and CRUD events
API access to resources, including those initiated by integrations
Git events, such as pushing, pulling, or cloning of code
GitHub maintains most audited events in logs for a configurable period of up to six months, while Git events are retained for seven days. Data from the logs is available to administrators within the GitHub UI, via the API, and via streaming.
Audit logs are available at both the enterprise account and organization level.
Viewing the audit log
You can view a time-limited audit log of events, minus Git events, in the user interface at both the enterprise and organization levels under their respective settings pages. Git events are only available through export or streaming of the audit log, not the user interface view, because of the high volume of events associated with this category. By default, only events from the past three months are displayed in the user interface. Older events up to six months past may be viewed by specifying a date range using GitHub search syntax with the created parameter.
If you want a record of audit events that persists longer than these limits, you’ll want to set up audit log streaming or automate log export as described below. GitHub strongly recommends that enterprise customers set up some form of audit log streaming or automation so that they can retain this critical source of security data.
Audit log streaming
You can configure audit log streaming at the enterprise account level to ensure all data captured is held within your preferred log management system and retained in accordance with existing policies. This is one method to access Git event data. The audit log retains Git events for seven days, but provided you are streaming and pause for no more than seven days, you’ll experience no loss of that data.
The benefits of streaming audit data include:
Data exploration. You can examine streamed events using your preferred tool for querying large quantities of data. The stream contains both audit events and Git events across the entire enterprise account.
Data analysis. Streamed data is useful for ongoing large-scale analysis, such as for anomaly detection via tools like Defender for DevOps and the GitHub App for Splunk.
Data continuity. You can pause the stream for up to seven days without losing any audit data.
Data retention. You can keep your exported audit logs and Git events data as long as you need to for reporting and audits, as well as for a quick response in case of a security incident or other urgent data need.
GitHub currently supports native streaming integration with Azure Events Hubs, Datadog, and Splunk, and also has the ability to directly write to AWS S3, Azure Blob Storage, and Google Cloud Storage.
Audit log export and API
If audit log streaming won’t work for you, or you need a one-time data export or a more targeted set of events, you can also use the audit log export and API options to retrieve audit log data at both the enterprise and organization levels. Exporting the audit log provides a downloadable JSON or CSV file. When you export audit log events, you can further filter your export by querying one or more of the supported qualifiers to filter for specific log events.
Exporting your audit logs also provides another method to access Git events data. The audit log retains Git events for export for a rolling seven days. Git events are exportable only in JSON format. Unlike audit log data, you cannot query for specific Git events to filter and export in the audit log user interface. Additionally, when you export Git events, events that were initiated via the web browser, or the REST or GraphQL APIs, are not included. For example, when a user merges a pull request in the web browser, changes are pushed to the base branch, but the Git event for that push is not included in the export.
The enterprise and organization audit logs can also be queried via REST API. However, if your end goal is long-term monitoring and reporting on your logs, GitHub strongly recommends using the audit log streaming option over the API. You’ll avoid having to concern yourself with API authentication and rate limit constraints, and you’ll be able to configure your monitoring and reporting exactly how you’d like in your data system of choice.
We integrated our audit logs with our security information and event management (SIEM) platform to create a variety of automated alerts around events on GitHub. For example, we use branch protection, but we also allow it to be overridden by policy for certain scenarios, such as an active security incident where you might need to bypass the CI checks or approval flow to respond. This integration provides visibility and allows us to override branch protection safely.
Audit log configuration
By default, GHEC audit logs do not display the source IP address for events. Optionally, to ensure compliance and respond to threats, you can enable a configuration option at the enterprise and/or organization levels to display the full IP address associated with the actor responsible for each event. Actors are typically users, but can also be apps or integrations. If you choose to display IP addresses for your enterprise account, the IP addresses will appear in both your enterprise's audit log and the audit log of every organization owned by your enterprise.
When the IP address display feature is enabled, the audit log displays an IP address when an actor in the enterprise interacts with a resource owned by your enterprise or an organization in your enterprise.
Although GitHub’s account terms have users agree to the collection of their IP addresses as a condition of using the platform, you are responsible for meeting any legal obligations that accompany the viewing or storage of IP addresses displayed within your organization's audit log as part of enabling the IP address display feature. If you use the standard user model, you will only see an IP address logged when users take actions associated with your enterprise itself, or private or internal repositories.
You can also disable the display of IP addresses in the audit log at any time if enabled.
Up next: Administration and governance essentials module wrap-up
We’ve covered a lot over these nine guides. Have you been taking notes? No worries, we have, and we’ll make sure to give you a list of the must-haves before we dive into the next module.