The audit log is the answer to every question that starts with “who”.
It is also a rolling window rather than an archive, and the most common audit log failure is discovering that the event you need aged out before anybody thought to keep it.
The short answer
Section titled “The short answer”The audit log records administrative and configuration events across the enterprise: membership changes, permission grants, repository creation and deletion, visibility changes, policy changes, and much else.
Retention is 180 days.
Git events are different. GitHub documents that “The audit log retains Git events for seven days.” On GitHub Enterprise Cloud, Git events are available via the REST API, with that seven-day retention.
API request events are a separate, newer category, documented as being in public preview, available only for Enterprise Managed Users enterprises and GitHub Enterprise Cloud with data residency, delivered by streaming only, and requiring enablement in the audit log settings.
Which means: if you want any of this beyond the retention window, stream it to somewhere you control.
Who reads it, and when
Section titled “Who reads it, and when”An audit log with no reader is a compliance artifact rather than a control, and the difference shows up in an incident.
Incident responders, during an investigation. The most important reader, and usually the one without access.
The platform team, for governance drift and process metrics. The regular reader, and the one who catches problems early.
Security engineering, for detection. Streaming into a SIEM makes GitHub events part of the same detection surface as everything else, which is the outcome worth aiming for.
Auditors, retrospectively, asking for evidence of a specific control operating. See compliance evidence.
Organisation owners, occasionally, for their own organisation.
The access question follows from this list. If the people who need to read it during an incident cannot reach it without an enterprise owner, the log is less useful than it appears. Streaming to a destination they already have solves that without granting enterprise ownership to responders.
And the training question. Somebody who has never queried the log will not do so effectively at 2 a.m. Half an hour of shared practice, once, with the runbook queries, is the intervention.
What is recorded
Section titled “What is recorded”The categories, rather than an exhaustive list, because the list is long and changes.
Membership and access. Members added and removed, teams created and modified, team membership changes, repository permission grants, outside collaborator invitations, role assignments.
Repository lifecycle. Created, deleted, renamed, transferred, archived, visibility changed. These are the irreversible ones, and they are the events most worth alerting on.
Policy and configuration. Enterprise policy changes, ruleset creation and modification, organisation settings, branch protection changes.
Authentication and identity. SSO configuration changes, SCIM provisioning events, credential authorisation, session activity.
Applications and integrations. App installations, permission changes, webhook configuration, deploy key creation.
Security. Secret scanning alerts, code scanning configuration, security policy changes.
Actions. Workflow-related configuration, runner registration, self-hosted runner group changes.
Each event carries an actor, a timestamp, an action name and contextual fields. The actor is what makes the log useful and what makes machine identity governance matter — an action attributed to a shared token names the token’s owner, not the process.
Git events and the seven-day window
Section titled “Git events and the seven-day window”A separate category with much shorter retention. GitHub documents that Git events are retained for seven days.
What they cover: clone, fetch and push operations.
Which makes them the answer to a specific and important question: has this repository been cloned, by whom, and when. That question arises in exactly two circumstances — a suspected data exfiltration, and an investigation into a compromised credential — and both are typically detected more than seven days after the fact.
On GitHub Enterprise Cloud, Git events are available through the REST API, subject to that retention.
The practical consequence: if answering “who cloned this” matters to your organisation, you must be streaming Git events continuously. There is no retrospective option.
This is the strongest argument for streaming, stronger than the 180-day question, because seven days is short enough that the window closes before most investigations begin.
API request events
Section titled “API request events”Documented as being in public preview and subject to change.
Available only for Enterprise Managed Users enterprises and GitHub Enterprise Cloud with data residency.
Delivered by streaming only — not through the interface or the standard API query path.
Must be enabled in the audit log settings.
What they add: visibility into API requests, which is the layer beneath the semantic events the main audit log records. Useful for understanding automation behaviour and for detecting unusual access patterns.
Enterprise, organisation and repository scope
Section titled “Enterprise, organisation and repository scope”The log exists at more than one level, and knowing which one to look at saves time.
The enterprise audit log covers events across every organisation in the enterprise. This is the one to use for anything cross-cutting, and the one enterprise owners have access to.
Organisation audit logs cover a single organisation. Available to organisation owners, which matters because it means an organisation owner can investigate their own events without enterprise access.
Repository-level information is not a separate audit log so much as a filter — events relating to a repository, visible in the scopes above.
Which scope you can reach depends on your role, and that has a practical consequence: an investigation that requires enterprise scope needs an enterprise owner, and enterprise owners are a small group. If incident response requires audit log access at short notice, make sure the responders can get it — or that somebody who can is reachable.
Do not grant enterprise ownership for audit access alone. It is a very large grant for a read-only need. Streaming to a destination where responders already have access solves this properly: the data is in your SIEM, the responders query it there, and nobody needs enterprise ownership to answer a question.
That is an underrated argument for streaming. It is usually justified by retention; the access model is the second reason and frequently the more immediately useful one.
Querying it
Section titled “Querying it”The interface supports filtering by actor, action, repository and date range, and is where most investigation starts.
The REST API returns events programmatically, which is what you need for anything systematic.
The GraphQL API exposes audit log entries for some scopes.
Search syntax matters. Learning the qualifiers — actor, action, created, repo — turns a scroll through thousands of events into a query. It is worth spending twenty minutes on this before an incident rather than during one.
Common queries worth knowing:
- Every action by a specific actor over a period, which is the offboarding and incident query
- Repository deletions, transfers and visibility changes, which are the irreversible events
- Permission grants above a threshold
- SSO and SCIM configuration changes, which are the highest-consequence events in the log
- App installations and permission changes
Practise them. The first time somebody asks “who deleted that repository”, the answer should take two minutes.
What an event looks like
Section titled “What an event looks like”Understanding the shape of an event makes the queries obvious.
Every event has an action, a dotted name identifying what happened — a repository being created, a team member being added, a policy being changed. The action name is the primary filter and it is worth browsing the available actions once to see what exists.
Every event has an actor, the account that performed it. For a person, their username. For an app, the app. For an action taken via a token, the token’s owner — which is why shared credentials degrade the log’s usefulness.
Every event has a timestamp, and time-range filtering is how most investigations are scoped.
Most events have a context object: the repository, the organisation, the team, the user affected. This is what lets you ask “everything that happened to this repository”.
Some events carry before-and-after values, which is what makes a permission change or a policy change intelligible rather than merely noted.
Some carry the source IP and the country, useful in a compromise investigation and worth knowing is there.
The fields vary by action, which means a query designed against one action’s shape may not work against another. When building automation over the log, be tolerant of missing fields rather than assuming a uniform schema.
What the log does not tell you
Section titled “What the log does not tell you”What was in the repository. A deletion event records that a repository was deleted, not what it contained.
What a person read. Beyond Git events within their seven-day window, ordinary read access is not enumerated.
Which role granted a capability. The log records that a person performed an action, not that they were able to because of a particular custom role.
Anything about content. Code changes are in Git history, not the audit log. The two are complementary and neither substitutes for the other.
Anything a deploy key did, in user terms. A deploy key does not act on behalf of a user, and the attribution reflects that.
Being clear about the boundaries prevents an investigation that assumes the log will answer a question it cannot, and prevents a control description that overclaims.
Retention, restated as a plan
Section titled “Retention, restated as a plan”Because retention is the property that determines everything else, it is worth converting into a decision.
Decide how long you need each category, and be specific:
Administrative events. How far back must you be able to answer “who granted this access”? For most organisations the honest answer is at least a year, driven by annual audit cycles. GitHub retains 180 days.
Git events. How far back must you be able to answer “who cloned this”? For an exfiltration investigation, the answer is however long detection takes, which is typically months. GitHub retains seven days.
API request events. Only available by streaming at all, so the question does not arise separately.
The gap between what you need and what GitHub retains is the streaming requirement, and stating it that way makes the case without needing a compliance argument.
Then decide where. A SIEM if you have one, object storage if you do not. Object storage is cheap, durable, and adequate — the data can be queried later even if it is not indexed today.
And decide the retention there. Streaming to a destination with a 30-day lifecycle policy solves nothing. Set the retention deliberately, aligned to the need you just stated.
Do this before anything else in this cluster. Every other operational capability — evidence, investigation, drift detection, metrics — is built on data you must already have been collecting.
Alerting
Section titled “Alerting”The log is most valuable when it is not being read.
Alert on irreversible actions. Repository deleted. Repository transferred out. Visibility changed to public. Each of these has a containment window measured in minutes to hours, and quarterly review is not a control.
Alert on identity configuration changes. SSO settings, SCIM configuration, certificate changes. Extremely low volume, extremely high consequence — a change is either a planned rotation you know about or something that should page somebody.
Alert on administrative role grants. Enterprise owner and organisation owner additions.
Alert on ruleset and policy deletion, which removes a control silently.
Keep the alert list short. An alerting configuration that fires daily gets muted. These categories are all genuinely rare in a healthy enterprise, which is exactly what makes them alertable.
Route them to a team, not a person. And include enough context in the alert that the recipient can decide whether it matters without opening three tabs.
Investigations worth rehearsing
Section titled “Investigations worth rehearsing”Six questions that will be asked, with the query shape for each. Rehearsing these is a two-hour exercise that pays for itself the first time.
“Who deleted this repository?” Filter by the deletion action and the repository name over the relevant period. The event names the actor and the time. Follow up by checking what else that actor did around the same time.
“Who gave this person admin?” Filter by the affected user and permission-change actions. The event should show the grant, the granter and the level.
“When did this repository become public?” Visibility change actions, filtered by repository. If the event is not in the window, that is itself informative — it happened more than 180 days ago.
“What did this departing person do in their last two weeks?” Filter by actor over the date range and read everything. Look specifically for new credentials, new collaborators, workflow file changes and pushes to protected branches.
“Has anybody cloned this repository?” Git events, seven-day window. If the question concerns anything older, the answer is only available if you were streaming.
“When did this control stop being enforced?” Ruleset and policy modification actions. A control that disappeared has an event, and finding it is the difference between “we do not know” and a specific date and actor.
Write these down as saved queries or as a short runbook. The value is not the queries themselves — it is that under pressure, somebody has a starting point rather than a search box.
Using the log proactively
Section titled “Using the log proactively”Most organisations use the audit log reactively, and the proactive uses are cheaper and more valuable.
Detect governance drift. Rulesets modified, policies changed, bypass lists extended. These are rare events with real consequences, and a weekly digest of them is a governance review that costs nothing.
Detect unmanaged access paths. New deploy keys, new outside collaborators, new app installations. Each is an access grant, and a digest turns them into something reviewable at the point of creation rather than at the next quarterly review.
Detect metadata gaps. Repository creation events with no subsequent custom property set. This catches the repositories that fall through every targeted policy, at creation rather than a year later.
Measure process compliance. How many repositories were created through the governed path versus directly. How many permission grants went to teams versus individuals. These are process metrics available for free from data you already have.
Feed the access picture. Grants and revocations from the log complement the point-in-time snapshots described in access reviews — the snapshot says what is, the log says what changed.
All of which is easier once streaming exists, because the data is queryable in a system built for querying rather than through paginated API calls.
Common mistakes
Section titled “Common mistakes”Assuming 180-day retention applies to Git events. They are retained for seven days.
Not streaming. Retention is a rolling window that cannot be extended retroactively.
Discovering the search syntax during an incident. Learn it beforehand.
Expecting the log to record content. Code changes are in Git history.
Relying on API request events without checking availability. Public preview, restricted configurations, streaming only.
Quarterly review as the control for irreversible actions. The containment window is much shorter.
Too many alerts. They get muted, and then the important one is missed.
Attributing an action to a person when a shared token was used. The actor is the token’s owner, not the process.
Automating access to it
Section titled “Automating access to it”Once you go beyond ad-hoc queries, the API is the interface, and a few things are worth knowing before you build against it.
Pagination is the main mechanic. The log is large and results are paged. A collector must follow pages to completion rather than reading the first one and stopping — an easy bug that produces silently incomplete data.
Rate limits apply. A backfill over 180 days of a busy enterprise is a lot of requests. Build for throttling and resumption rather than assuming a clean run.
Authenticate as something durable. A collector using a personal access token stops working when that person leaves, and the failure is silent — the log simply stops being collected. A GitHub App is the right identity; see machine identities.
Do not build a collector if streaming is available. Streaming delivers events to a destination continuously, without pagination, rate limits or a collector to maintain. A polling collector is what you build when streaming is unavailable, and it is strictly worse.
Handle the field variation. Actions carry different fields, and code that assumes a uniform schema breaks on the first unusual event.
Record what you collected. A collector should log its own progress — which pages, which time ranges, whether it completed. Otherwise a gap in the data is indistinguishable from a quiet period.
And monitor it. A collection job that has silently stopped is the failure mode, and the symptom is data that looks fine until somebody asks about a period that was never collected.
Volume and what it implies
Section titled “Volume and what it implies”A practical note, because the log is larger than people expect and that shapes what you build.
A busy enterprise generates a great deal of it. Every membership change, every permission grant, every workflow configuration touch, every app action. An estate of a thousand repositories with active automation produces a volume where reading it all is not an option.
Which means filtering is the primary skill, not reading. A query that returns four thousand events has not answered anything.
Automation is a large fraction of the volume. Bots opening pull requests, apps updating statuses, dependency tools creating branches. This is normal and it drowns human activity in any unfiltered view.
Which is an argument for excluding known automation in routine views, while emphatically not excluding it in an incident — a compromised app is exactly the case where automation activity is the thing you need to see.
Storage cost is modest. Compressed audit events are small, and even years of them for a large enterprise is not a significant storage bill compared to the value of being able to answer a question about last March.
Query cost may not be. If you stream into a SIEM that charges by ingestion, the volume matters commercially. Object storage with occasional query is the cheaper pattern where budget is a constraint, and it is entirely adequate for retrospective investigation.
Decide this deliberately. The choice between “everything into the SIEM” and “everything into object storage, selected events into the SIEM” is a real cost decision, and making it consciously beats discovering it on an invoice.
Mental model
Section titled “Mental model”The audit log answers “who did what, and when” for administrative actions, within a rolling window. It does not answer “what was in it”, “who read it” beyond seven days, or anything about code content. Its value is proportional to whether you were streaming it before the question arose.
What you learned
Section titled “What you learned”- The audit log records administrative and configuration events with 180-day retention
- GitHub documents that the audit log retains Git events for seven days
- Git events on GitHub Enterprise Cloud are available via the REST API within that window
- API request events are in public preview, limited to EMU and data residency enterprises, and streaming-only
- The log records actors and actions but not repository content or ordinary read access
- Irreversible actions — deletion, transfer, visibility change — warrant alerts rather than periodic review
- Identity configuration changes are the highest-consequence and lowest-volume events to alert on
- Search qualifiers should be learned before an incident, not during one
- Streaming is the only way to retain anything beyond the window
Exercise
Section titled “Exercise”Use an enterprise you have access to.
-
Open the audit log. Find the oldest event visible. Predict: how far back does it go?
-
Query for repository deletions in the last ninety days. How many, and by whom?
-
Query for visibility changes. Were any of them widenings?
-
Query for SSO or SCIM configuration changes. Can you account for each one?
-
Pick a colleague and query every action by them in the last month. Predict: how long did the query take you to construct?
-
Try to find Git clone events from two weeks ago. Predict: what happens?
-
List the events you would alert on. Estimate the volume of each per month.
-
Determine whether streaming is configured. If not, that is the finding.