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

  1. Generate a personal access token (PAT) to authenticate your requests.
    You can do this through the user developer settings under personal access tokens.
  2. 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.
  3. 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.
  4. Now that you have your PAT and GraphQL client, it’s time to add the base URL.
    The Audit log API base URL is https://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.

  5. 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.

  6. 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: