The GitHub Enterprise Audit log API for GraphQL beginners
The newly shipped GitHut Audit log API allows you to make efficient queries for specific log data. Learn more about how to get started with the API.
Recently, GitHub announced an extension of the GitHub GraphQL API with our public beta release of the GitHub Audit log API for organizations using GitHub Enterprise. The initial release of the API exposes much of the same information you’d find in the “Audit log” section in the Settings tab of your organization.
Use the Audit log API to keep copies of your audit log data and monitor:
- Access to your organization or repository settings
- Changes in permissions
- Added or removed users in an organization, repository, or team
- Users promoted to administrators
- Organizations that have been added or removed
- Changes to permissions of a GitHub App
- Data for the current month and the last three months
You may have noticed this API is different than most of our other RESTful services. This is because the engineering team implemented a GraphQL interface with the intention of enabling you to make highly efficient queries for specific enterprise log entries. GraphQL can be tricky if you haven’t used it before, and while most of the concepts translate from REST, there are a few key differences. To help you get started with the Audit log API, we’re sharing a few useful steps, tips, and snippets of an actual query.
Create a query to get started
- Generate a personal access token (PAT) to authenticate your requests.
You can do this through the user developer settings under personal access tokens. - Grant full permissions to the PAT for both the repository and
admin:org
.
If SAML SSO isn’t enabled for your enterprise, revisit the PAT section and enable SSO access.
- If you haven’t already, download a GraphQL client. There are many useful tools available for free, like Postman’s latest version, Insomnia and GraphiQL.
- Now that you have your PAT and GraphQL client, it’s time to add the base URL.
The Audit log API base URL ishttps://api.github.com/graphql
. This URL remains the same regardless of which entities you query—this is part of the magic of GraphQL. When making a request, don’t forget to POST the query with your PAT as the Bearer Token.
- Set the following values in the “Headers” tab:
{“Content-Type”: “application/json”, “Accept”: “application/vnd.github.audit-log-preview+json”}
This “Accept” header is where we are programmatically opting in to the beta.
- Now we create the GraphQL query where we’ll request our enterprise organization for the latest five log entries.
{ organization(login: "<org-name>") { auditLog(last: 5, query: "actor:<user-name>") { edges { node { ... on AuditEntry { # Get Audit Log Entry by 'Action' action actorLogin createdAt # User 'Action' was performed on user{ name email } } } } } } }
The results
A JSON response that matches the same schema as your request is returned, each node in the collection of “edges” includes an action, the user that initiated that action, when the action took place, and which user it affected. Notice each of the five nodes only include the information we specifically requested with our query. Your enterprise can gain valuable insights from the information this query returned—but also more broadly from the Audit log API.
Now that you’ve made your first GraphQL request to the Audit log API, you can start learning how your enterprise works and make data-driven decisions about auditing on your team. If you have any questions or need more information check out our best practices or contact your account management team or the GitHub Sales Team.
Learn more about the Audit log API
Tags:
Written by
Related posts
Inside the research: How GitHub Copilot impacts the nature of work for open source maintainers
An interview with economic researchers analyzing the causal effect of GitHub Copilot on how open source maintainers work.
OpenAI’s latest o1 model now available in GitHub Copilot and GitHub Models
The December 17 release of OpenAI’s o1 model is now available in GitHub Copilot and GitHub Models, bringing advanced coding capabilities to your workflows.
Announcing 150M developers and a new free tier for GitHub Copilot in VS Code
Come and join 150M developers on GitHub that can now code with Copilot for free in VS Code.