- Getting Started
- What is GraphQL?
- Breaking changes
- Available queries
- Generate updates for documentation
For those new to the GitLab GraphQL API, see Getting started with GitLab GraphQL API.
- The GitLab GraphQL API endpoint is located at
- Get an introduction to GraphQL from graphql.org.
- GitLab supports a wide range of resources, listed in the GraphQL API Reference.
To work with sample queries that pull data from public projects on GitLab.com,
see the menu options in the left-hand
documentation menu, under API > GraphQL at
The Getting started page includes different methods to customize GraphQL queries.
Explore the GraphQL API using the interactive GraphiQL explorer,
or on your self-managed GitLab instance on
See the GitLab GraphQL overview for more information about the GraphiQL Explorer.
GraphQL is a query language for APIs that allows clients to request exactly the data they need, making it possible to get all required data in a limited number of requests.
The GraphQL data (fields) can be described in the form of types, allowing clients to use client-side GraphQL libraries to consume the API and avoid manual parsing.
Since there’s no fixed endpoints and data model, new abilities can be added to the API without creating breaking changes. This allows us to have a versionless API as described in the GraphQL documentation.
We want the GraphQL API to be the primary means of interacting programmatically with GitLab. To achieve this, it needs full coverage - anything possible in the REST API should also be possible in the GraphQL API.
To help us meet this vision, the frontend should use GraphQL in preference to the REST API for new features.
There are no plans to deprecate the REST API. To reduce the technical burden of supporting two APIs in parallel, they should share implementations as much as possible.
The GitLab GraphQL API is versionless and changes are made to the API in a way that maintains backwards-compatibility.
Occassionally GitLab needs to change the GraphQL API in a way that is not backwards-compatible. These changes include the removal or renaming of fields, arguments or other parts of the schema.
In these situations, GitLab follows a Deprecation and removal process where the deprecated part of the schema is supported for a period of time before being removed.
Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations.
Parts of the schema marked for removal from the GitLab GraphQL API are first deprecated but still available
for at least six releases, and then removed entirely.
Removals occur at
The process is as follows:
- The item is marked as deprecated in the schema. It will be displayed as deprecated in the GraphQL API Reference and in introspection queries.
- Removals are announced at least one release prior in the Deprecations
section of the release post (at or prior to
X.5releases). release post (at or prior to
Items meeting criteria are removed in
X.6and added to:
This gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries.
When an item is deprecated or removed, an alternative is provided if available.
A field marked as deprecated in
12.7 can be used until its removal in
View the fields, enums, and other items we removed from the GraphQL API.
The GraphQL API includes the following queries at the root level:
project: Project information, with many of its associations such as issues and merge requests.
group: Basic group information and epics are currently supported.
user: Information about a particular user.
namespace: Within a namespace it is also possible to fetch
currentUser: Information about the currently logged in user.
users: Information about a collection of users.
metaData: Metadata about GitLab and the GraphQL API.
snippets: Snippets visible to the currently logged in user.
New associations and root level objects are constantly being added. See the GraphQL API Reference for up-to-date information.
Root-level queries are defined in
GitLab supports batching queries into a single request using apollo-link-batch-http. More information about multiplexed queries is also available for GraphQL Ruby, the library GitLab uses on the backend.
The following limits apply to the GitLab GraphQL API.
By default, connections return at most
100 records (“nodes”) per page,
and this limit applies to most connections in the API. Particular connections
may have different max page size limits that are higher or lower.
The GitLab GraphQL API scores the complexity of a query. Generally, larger queries will have a higher complexity score. This limit is designed to protect the API from performing queries that could negatively impact its overall performance.
The complexity of a single query is limited to a maximum of:
200for unauthenticated requests.
250for authenticated requests.
There is no way to discover the complexity of a query except by exceeding the limit.
If a query exceeds the complexity limit an error message response will be returned.
In general, each field in a query will add
1 to the complexity score, although
this can be higher or lower for particular fields. Sometimes the addition of
certain arguments may also increase the complexity of a query.
Requests time out at 30 seconds.
The GitLab GraphQL reference is available.
It is automatically generated from the GitLab GraphQL schema and embedded in a Markdown file.
If you’ve changed the GraphQL schema, you should set up an MR to gain approval of your changes. To generate the required documentation and schema, follow the instructions given in the Rake tasks for developers page.
Be sure to run these commands using the GitLab Development Kit.