GitHub’s audit log API lets you see who did what, when, and where within your organization.
Let’s see it in action. Imagine you want to find out who recently added a new member to your organization. You can use curl to query the API.
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
"https://api.github.com/orgs/YOUR_ORG_NAME/audit/log?phrase=added+member"
Replace YOUR_GITHUB_TOKEN with a personal access token that has read:org scope, and YOUR_ORG_NAME with your GitHub organization’s name. This command fetches audit events that include the phrase "added member." The output will be a JSON array of events, each detailing the actor, the action, the target, and the timestamp.
The audit log API is your central source of truth for organizational security and compliance. It records significant events like user access changes, repository modifications, team management, and application integrations. By leveraging this API, you can automate security monitoring, detect suspicious activity, and generate reports for compliance audits.
Internally, the API exposes a stream of events that are indexed for querying. You can filter these events using various parameters:
phrase: A free-text search term.actor: The username of the person or application that performed the action.action: A specific event type (e.g.,add_member,remove_member,create_repository). You can find a comprehensive list of actions in the GitHub documentation.beforeandafter: Timestamps to define a date range for the audit events.pageandper_page: For paginating through the results.
For instance, to find all repository creations by a specific user octocat within your organization my-company between two dates:
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
"https://api.github.com/orgs/my-company/audit/log?action=create_repository&actor=octocat&before=2023-10-27T10:00:00Z&after=2023-10-26T00:00:00Z"
This allows for granular investigation. You might want to track all instances where a user was removed from an organization, or when sensitive repositories were accessed. The read:org scope on your personal access token is crucial for accessing this data. Without it, your requests will be unauthorized.
When you’re analyzing audit logs, you’ll often encounter events with the action field. A common misconception is that these actions are simple string matches. However, GitHub’s audit log API uses a structured event model, and the action field represents a specific, enumerated type of event. For example, add_member is a distinct event type, not just a string that happens to contain "add" and "member." This means you can reliably filter for specific actions like create_repository, delete_repository, transfer_repository, add_team_membership, and remove_team_membership with precision.
The next step in understanding GitHub’s event-driven ecosystem is exploring the Webhooks API, which allows you to react in real-time to these very same events.