Skip to content

Set up an Audit Report with GraphQL

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

This page describes how you can use the GraphiQL explorer to set up an audit report for a specific subset of users.

You can run the same query directly via a HTTP endpoint, using cURL. For more information, see our guidance on getting started from the command line.

The example users query looks for a subset of users in a GitLab instance either by username or Global ID. The query includes:

pageInfo

This contains the data needed to implement pagination. GitLab uses cursor-based pagination. For more information, see Pagination in the GraphQL documentation.

nodes

In a GraphQL query, nodes is used to represent a collection of nodes on a graph. In this case, the collection of nodes is a collection of User objects. For each one, we output:

  • Their user's id.
  • The membership fragment, which represents a Project or Group membership belonging to that user. Outputting a fragment is denoted with the ...memberships notation.

The GitLab GraphQL API is extensive and a large amount of data for a wide variety of entities can be output. See the official reference documentation for the most up-to-date information.

Set up the GraphiQL explorer

This procedure presents a substantive example that you can copy and paste into GraphiQL explorer. GraphiQL explorer is available for:

  1. Copy the following code excerpt:

    {
      users(usernames: ["user1", "user2", "user3"]) {
        pageInfo {
          endCursor
          startCursor
          hasNextPage
        }
        nodes {
          id
          ...memberships
        }
      }
    }
    
    fragment membership on MemberInterface {
      createdAt
      updatedAt
      accessLevel {
        integerValue
        stringValue
      }
      createdBy {
        id
      }
    }
    
    fragment memberships on User {
      groupMemberships {
        nodes {
          ...membership
          group {
            id
            name
          }
        }
      }
    
      projectMemberships {
        nodes {
          ...membership
          project {
            id
            name
          }
        }
      }
    }
  2. Open the GraphiQL explorer tool.

  3. Paste the query listed above into the left window of your GraphiQL explorer tool.

  4. Select Play to get the result shown here:

GraphiQL explorer search for boards

NOTE: The GraphQL API returns a GlobalID, rather than a standard ID. It also expects a GlobalID as an input rather than a single integer.

This GraphQL query returns the groups and projects that the user has been explicitly made a member of. Since the GraphiQL explorer uses the session token to authorize access to resources, the output is limited to the projects and groups accessible to the currently authenticated user.

If you've signed in as an instance administrator, you would have access to all records, regardless of ownership.

For more information on: