Run GraphQL API queries and mutations
This guide demonstrates basic usage of the GitLab GraphQL API.
Read the GraphQL API style guide for implementation details aimed at developers who wish to work on developing the API itself.
Running examples
The examples documented here can be run using:
GraphiQL
GraphiQL (pronounced “graphical”) allows you to run real GraphQL queries against the API interactively. It makes exploring the schema easier by providing a UI with syntax highlighting and autocompletion.
For most people, using GraphiQL will be the easiest way to explore the GitLab GraphQL API.
You can either use GraphiQL:
- On GitLab.com.
- On your self-managed GitLab instance on
https://<your-gitlab-site.com>/-/graphql-explorer
.
Sign in to GitLab first to authenticate the requests with your GitLab account.
To get started, refer to the example queries and mutations.
Command line
You can run GraphQL queries in a curl
request on the command line on your
local computer. The requests POST
to /api/graphql
with the query as the payload. You can authorize your request by generating a
personal access token to use as
a bearer token.
This token requires at least the read_api
scope.
Example:
GRAPHQL_TOKEN=<your-token>
curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" --request POST \
--data "{\"query\": \"query {currentUser {name}}\"}"
To nest strings in the query string,
wrap the data in single quotes or escape the strings with \\
:
curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" --request POST \
--data '{"query": "query {project(fullPath: \"<group>/<subgroup>/<project>\") {jobs {nodes {id duration}}}}"}'
# or "{\"query\": \"query {project(fullPath: \\\"<group>/<subgroup>/<project>\\\") {jobs {nodes {id duration}}}}\"}"
Rails console
GraphQL queries can be run in a Rails console session. For example, to search projects:
current_user = User.find_by_id(1)
query = <<~EOQ
query securityGetProjects($search: String!) {
projects(search: $search) {
nodes {
path
}
}
}
EOQ
variables = { "search": "gitlab" }
result = GitlabSchema.execute(query, variables: variables, context: { current_user: current_user })
result.to_h
Queries and mutations
The GitLab GraphQL API can be used to perform:
- Queries for data retrieval.
- Mutations for creating, updating, and deleting data.
id
refers to a
Global ID,
which is an object identifier in the format of "gid://gitlab/Issue/123"
.GitLab GraphQL Schema outlines which objects and fields are available for clients to query and their corresponding data types.
Example: Get only the names of all the projects the currently authenticated user can
access (up to a limit) in the group gitlab-org
.
query {
group(fullPath: "gitlab-org") {
id
name
projects {
nodes {
name
}
}
}
}
Example: Get a specific project and the title of Issue #2.
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issue(iid: "2") {
title
}
}
}
Graph traversal
When retrieving child nodes use:
- The
edges { node { } }
syntax. - The short form
nodes { }
syntax.
Underneath it all is a graph we are traversing, hence the name GraphQL.
Example: Get the name of a project, and the titles of all its issues.
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues {
nodes {
title
description
}
}
}
}
More about queries: GraphQL documentation
Authorization
Authorization uses the same engine as the GitLab application (and GitLab.com). If you’ve signed in to GitLab and use GraphiQL, all queries are performed as you, the authenticated user. For more information, read the GitLab API documentation.
Mutations
Mutations make changes to data. We can update, delete, or create new records. Mutations generally use InputTypes and variables, neither of which appear here.
Mutations have:
- Inputs. For example, arguments, such as which emoji reaction you’d like to add, and to which object.
- Return statements. That is, what you’d like to get back when it’s successful.
- Errors. Always ask for what went wrong, just in case.
Creation mutations
Example: Let’s have some tea - add a :tea:
reaction emoji to an issue.
mutation {
awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
name: "tea"
}) {
awardEmoji {
name
description
unicode
emoji
unicodeVersion
user {
name
}
}
errors
}
}
Example: Add a comment to the issue. In this example, we use the ID of the
GitLab.com
issue. If you’re using a local instance, you must get the ID of an
issue you can write to.
mutation {
createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
body: "*sips tea*"
}) {
note {
id
body
discussion {
id
}
}
errors
}
}
Update mutations
When you see the result id
of the note you created, take a note of it. Let’s
edit it to sip faster.
mutation {
updateNote(input: { id: "gid://gitlab/Note/<note ID>",
body: "*SIPS TEA*"
}) {
note {
id
body
}
errors
}
}
Deletion mutations
Let’s delete the comment, because our tea is all gone.
mutation {
destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) {
note {
id
body
}
errors
}
}
You should get something like the following output:
{
"data": {
"destroyNote": {
"errors": [],
"note": null
}
}
}
We’ve asked for the note details, but it doesn’t exist anymore, so we get null
.
More about mutations: GraphQL Documentation.
Update project settings
You can update multiple project settings in a single GraphQL mutation.
This example is a workaround for the major change
in CI_JOB_TOKEN
scoping behavior.
mutation DisableCI_JOB_TOKENscope {
projectCiCdSettingsUpdate(input:{fullPath: "<namespace>/<project-name>", inboundJobTokenScopeEnabled: false, jobTokenScopeEnabled: false}) {
ciCdSettings {
inboundJobTokenScopeEnabled
jobTokenScopeEnabled
}
errors
}
}
Introspection queries
Clients can query the GraphQL endpoint for information about its schema by making an introspection query.
The GraphiQL Query Explorer uses an introspection query to:
- Gain knowledge about the GitLab GraphQL schema.
- Do autocompletion.
- Provide its interactive
Docs
tab.
Example: Get all the type names in the schema.
{
__schema {
types {
name
}
}
}
Example: Get all the fields associated with Issue. kind
tells us the enum
value for the type, like OBJECT
, SCALAR
or INTERFACE
.
query IssueTypes {
__type(name: "Issue") {
kind
name
fields {
name
description
type {
name
}
}
}
}
More about introspection: GraphQL documentation
Query complexity
The calculated complexity score and limit for a query can be revealed to clients by
querying for queryComplexity
.
query {
queryComplexity {
score
limit
}
project(fullPath: "gitlab-org/graphql-sandbox") {
name
}
}
Sorting
Some of the GitLab GraphQL endpoints allow you to specify how to sort a collection of objects. You can only sort by what the schema allows you to.
Example: Issues can be sorted by creation date:
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(sort: created_asc) {
nodes {
title
createdAt
}
}
}
}
Pagination
Pagination is a way of only asking for a subset of the records, such as the
first ten. If we want more of them, we can make another request for the next
ten from the server in the form of something like please give me the next ten records
.
By default, the GitLab GraphQL API returns 100 records per page. To change this
behavior, use first
or last
arguments. Both arguments take a value, so
first: 10
returns the first ten records, and last: 10
the last ten records.
There is a limit on how many records are returned per page, which is generally
100
.
Example: Retrieve only the first two issues (slicing). The cursor
field gives
us a position from which we can retrieve further records relative to that one.
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 2) {
edges {
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
Example: Retrieve the next three. (The cursor value
eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0
could be different, but it’s the cursor
value returned for the second issue
returned above.)
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
edges {
node {
title
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
More about pagination and cursors: GraphQL documentation