GraphQL API Directives
A directive provides a way to describe alternate runtime execution and type validation behavior in a GraphQL document. For more information, see the GraphQL directive documentation.
Deprecated items are planned to be removed in a future release. For more information, see the GitLab deprecation process.
deprecated
Marks an element of a GraphQL schema as no longer supported.
deprecated locations
ARGUMENT_DEFINITIONENUM_VALUEFIELD_DEFINITIONINPUT_FIELD_DEFINITION
deprecated arguments
| Name | Type | Description | Default |
|---|---|---|---|
reason | String | Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted in Markdown. | "No longer supported" |
gl_introduced
Marks a field as introduced in a specific version. Fields tagged with the current milestone or a later one return null when the field is absent from the schema.
gl_introduced locations
FIELDINLINE_FRAGMENT
gl_introduced arguments
| Name | Type | Description |
|---|---|---|
version | String! | The version when this field was introduced (e.g. ‘18.1.0’). |
granularScope
Declares the granular personal access token permissions required to access a field or type, along with the authorization boundary (project, group, user, or instance) those permissions apply to. A field or type can also opt out of granular token authorization by giving a skip reason.
granularScope locations
FIELD_DEFINITIONOBJECT
This is a repeatable directive and can be used with different arguments at the same location.
granularScope arguments
| Name | Type | Description |
|---|---|---|
assignableWhen | [String!] | Conditions the current user must meet for the permissions to be offered in the token creation UI. Not a security control: the type, mutation, or field must still enforce the conditions. Valid values: admin, gitlab_team_member, saas, self_managed. |
boundary | String | Method name to call on the resolved object to extract the authorization boundary (Project/Group). Use when the object is already resolved (fields on types, nested fields). |
boundaryArgument | String | Argument name containing the authorization boundary (path or GlobalID). Use for mutations and query fields where the boundary is passed as an argument. |
boundaryType | PermissionBoundary | The type of authorization boundary (project, group, user, instance). Used for validation and documentation of the permission boundary. |
permissions | [String!] | Granular scope permissions required to access the field or type. |
skipReason | String | Reason the field or type intentionally opts out of granular token authorization. |
include
Directs the executor to include this field or fragment only when the if argument is true.
include locations
FIELDFRAGMENT_SPREADINLINE_FRAGMENT
include arguments
| Name | Type | Description |
|---|---|---|
if | Boolean! | Included when true. |
oneOf
Requires that exactly one field must be supplied and that field must not be null.
oneOf locations
INPUT_OBJECT
skip
Directs the executor to skip this field or fragment when the if argument is true.
skip locations
FIELDFRAGMENT_SPREADINLINE_FRAGMENT
skip arguments
| Name | Type | Description |
|---|---|---|
if | Boolean! | Skipped when true. |
specifiedBy
Exposes a URL that specifies the behavior of this scalar.
specifiedBy locations
SCALAR
specifiedBy arguments
| Name | Type | Description |
|---|---|---|
url | String! | The URL that specifies the behavior of this scalar. |