> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Query and mutate data with GitLab GraphQL agents

> Connect Guild agents to the GitLab.com GraphQL API. Run any query or mutation using a personal access token, with server-side credentials and policy controls.

Integrations · GitLab GraphQL

A Guild agent can query and mutate any GitLab.com data through the GraphQL API, using a personal access token you connect once. Guild injects the token server-side so agent code never sees it, and credential policies let you restrict what each agent can reach before any request leaves Guild.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use GitLab GraphQL.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect GitLab GraphQL to your first agent.

## What the GitLab GraphQL integration exposes

The integration provides a single tool, `gitlab_graphql_graphql_query`, which sends one GraphQL document to the GitLab.com GraphQL API. The tool supports both queries and mutations, so an agent can retrieve or modify GitLab data in one call. Tools are prefixed `gitlab_graphql_` and you can use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only the ones your agent needs.

## How it works

**1. Open credentials settings**

In Guild, go to **Access & setup > Credentials** and click **Connect**. Select **gitlab-graphql** from the list.

**2. Paste your access token**

Paste your GitLab personal access token into the **API Key** field. Guild stores it and sends it as a bearer token in the `Authorization` header on every request.

**3. Scope the credential**

Choose account, workspace, member, or agent scope. See [Credentials](https://docs.guild.ai/platform/credentials.md) for the full scope options and how Guild resolves which credential an agent uses.

## Why GitLab GraphQL access needs governing

GitLab GraphQL mutations can create, update, or delete data across projects, issues, merge requests, and more. A single tool that accepts any GraphQL document gives an agent broad reach, so limiting what it can do matters. [Credential policies](https://docs.guild.ai/platform/credential-policies.md) let you write ALLOW and DENY rules that Guild's credential proxy enforces before any request reaches GitLab. You can restrict by operation name, HTTP method, agent, or workspace, and a matching DENY rule always wins over any ALLOW rule.

Guild injects the personal access token server-side only after the policy check passes. The token never enters the agent's code, container, prompt, or state. You can scope the credential to a single agent or workspace so it never serves other workspaces. For details on how Guild chooses which credential to use and how the proxy works, see [Credentials](https://docs.guild.ai/platform/credentials.md) and [Credential policies](https://docs.guild.ai/platform/credential-policies.md).

## About the GitLab GraphQL integration

This integration gives agents access to the GitLab.com GraphQL API through a single tool. Agents can send any GraphQL query or mutation to retrieve or modify GitLab data. A personal access token is required to authenticate requests. The integration is `guildai~gitlab-graphql`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect GitLab GraphQL**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **gitlab-graphql**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { GitlabGraphqlTools } from "@guildai-services/guildai~gitlab-graphql"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with GitLab GraphQL.",
  tools: { ...GitlabGraphqlTools },
})
```

### Selecting specific tools

Tools are named with the `gitlab_graphql_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~gitlab-graphql`:

| Tool | What it does |
| - | - |
| `gitlab_graphql_graphql_query` | Send one GraphQL document. |

## Frequently asked questions

> [accordion] Can I run GraphQL mutations, not just queries?
>
> Yes. The `gitlab_graphql_graphql_query` tool sends any GraphQL document, so agents can run mutations to modify GitLab data as well as queries to retrieve it.

> [accordion] Does my agent ever see the personal access token?
>
> No. Guild stores the token and adds it to requests server-side as a bearer token. The token never enters the agent's code, container, prompt, or state.

> [accordion] Can I limit which operations this agent is allowed to run?
>
> Yes. [Credential policies](https://docs.guild.ai/platform/credential-policies.md) let you write ALLOW and DENY rules scoped to specific agents, workspaces, or HTTP methods. The proxy enforces them before any request reaches GitLab.

> [accordion] Does this integration support webhook events from GitLab?
>
> Not yet. The catalog entry for `guildai~gitlab-graphql` lists no webhook events, so event-driven triggers from GitLab are not available through this integration.

## Put a governed agent on GitLab GraphQL this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use GitLab GraphQL.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect GitLab GraphQL to your first agent.

## Related

**Also runs on Guild:** [Azure DevOps](https://docs.guild.ai/integrations/azure-devops.md) · [Bitbucket](https://docs.guild.ai/integrations/bitbucket.md) · [GitHub](https://docs.guild.ai/integrations/github.md) · [GitLab](https://docs.guild.ai/integrations/gitlab-openapi.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)