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

# GitLab

> GitLab Scenario seeding parameters, nested fields, and examples

Use `gitlab` in `twins` and put this configuration under `seed_config.gitlab`.

GitLab with users, groups, projects, repository files, branches, issues, merge requests, CI pipelines, variables, and webhooks.

## Example seed

This is the complete Scenario request body for [creating a Scenario](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`.

```json theme={null}
{
  "name": "GitLab eval fixture",
  "twins": [
    "gitlab"
  ],
  "seed_config": {
    "gitlab": {
      "users": [
        {
          "id": 1,
          "username": "developer",
          "name": "Developer",
          "email": "developer@example.com"
        }
      ],
      "groups": [
        {
          "name": "Example Group",
          "path": "example-group",
          "visibility": "private"
        }
      ],
      "projects": [
        {
          "name": "project-name",
          "path": "project-name",
          "namespace_path": "example-group",
          "description": "Short project description",
          "visibility": "private",
          "default_branch": "main",
          "files": [
            {
              "path": "README.md",
              "branch": "main",
              "content": "file body text"
            }
          ],
          "branches": [
            {
              "name": "feature-branch",
              "ref": "main"
            }
          ],
          "issues": [
            {
              "title": "Issue title",
              "description": "Issue description",
              "labels": [
                "bug"
              ]
            }
          ],
          "merge_requests": [
            {
              "title": "MR title",
              "source_branch": "feature-branch",
              "target_branch": "main",
              "description": "MR description",
              "files": [
                {
                  "path": "src/app.ts",
                  "content": "complete file contents on the source branch"
                }
              ],
              "approved": false,
              "merged": false
            }
          ],
          "variables": [
            {
              "key": "FEATURE_FLAG",
              "value": "enabled"
            }
          ],
          "pipelines": [
            {
              "ref": "main"
            }
          ]
        }
      ]
    }
  }
}
```

## Parameters

The following fields belong directly inside `seed_config.gitlab`. Required nested fields are marked in their tables. Provider-native objects can contain service-specific fields beyond the representative record shapes below.

| Parameter | Type | Description |
| - | - | - |
| `users` | `object[]` | Users fixtures in provider-native format. |
| `groups` | `object[]` | Group fixtures or memberships in the format shown below. |
| `projects` | `object[]` | Projects fixtures in provider-native format. |
| `default_token` | `string` | Synthetic default token for GitLab API requests. |

## Resource fields

These tables describe the record shapes used by the example. Keep native field names and casing. Map keys such as property names, IDs, and metadata keys are supplied by your fixture.

### `users[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `integer` | Explicit resource identifier, when supported. |
| `username` | `string` | Username. |
| `name` | `string` | Human-readable name. |
| `email` | `string` | Main account email address. |

### `groups[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `path` | `string` | Path. |
| `visibility` | `string` | Visibility. |

### `projects[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `path` | `string` | Path. |
| `namespace_path` | `string` | Namespace path. |
| `description` | `string` | Description. |
| `visibility` | `string` | Visibility. |
| `default_branch` | `string` | Default branch. |
| `files` | `object[]` | Files fixtures in provider-native format. |
| `branches` | `object[]` | Branches fixtures in provider-native format. |
| `issues` | `object[]` | Issues fixtures in provider-native format. |
| `merge_requests` | `object[]` | Merge requests fixtures in provider-native format. |
| `variables` | `object[]` | Variables fixtures in provider-native format. |
| `pipelines` | `object[]` | Pipelines fixtures in provider-native format. |
| `namespace` | `string` | Namespace. |
| `repo_url` | `string` | Repo url. |
| `public_repo_url` | `string` | Public repo url. |
| `clone_url` | `string` | Clone url. |
| `source_repo_url` | `string` | Source repo url. |
| `source_ref` | `string` | Source ref. |
| `ref` | `string` | Ref. |
| `mrs` | `array` | Mrs fixtures in provider-native format. |
| `webhooks` | `object[]` | Webhook subscriptions or configurations. |
| `hooks` | `object[]` | Hooks fixtures in provider-native format. |

### `projects[].files[]`

| Parameter | Type | Description |
| - | - | - |
| `path` | `string` | Path. |
| `branch` | `string` | Branch. |
| `content` | `string` | Text content. |
| `encoding` | `string` | Encoding. |
| `commit_message` | `string` | Commit message. |

### `projects[].branches[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `ref` | `string` | Ref. |

### `projects[].issues[]`

| Parameter | Type | Description |
| - | - | - |
| `title` | `string` | Human-readable name. |
| `description` | `string` | Description. |
| `labels` | `string[]` | Custom label names or objects containing name. |
| `body` | `string` | Text content. |
| `state` | `string` | State. |
| `comments` | `array` | Comments fixtures in provider-native format. |
| `notes` | `array` | Notes fixtures in provider-native format. |
| `discussions` | `array` | Discussions fixtures in provider-native format. |

### `projects[].merge_requests[]`

| Parameter | Type | Description |
| - | - | - |
| `title` | `string` | Human-readable name. |
| `source_branch` | `string` | Source branch. |
| `target_branch` | `string` | Target branch. |
| `description` | `string` | Description. |
| `files` | `object[]` | Files fixtures in provider-native format. |
| `approved` | `boolean` | Enable or set approved behavior. |
| `merged` | `boolean` | Enable or set merged behavior. |
| `head` | `string` | Head. |
| `base` | `string` | Base. |
| `body` | `string` | Text content. |
| `state` | `string` | State. |
| `comments` | `array` | Comments fixtures in provider-native format. |
| `notes` | `array` | Notes fixtures in provider-native format. |
| `discussions` | `array` | Discussions fixtures in provider-native format. |

### `projects[].merge_requests[].files[]`

| Parameter | Type | Description |
| - | - | - |
| `path` | `string` | Path. |
| `content` | `string` | Text content. |

### `projects[].variables[]`

| Parameter | Type | Description |
| - | - | - |
| `key` | `string` | Key. |
| `value` | `string` | Value. |

### `projects[].pipelines[]`

| Parameter | Type | Description |
| - | - | - |
| `ref` | `string` | Ref. |

## API coverage and limitations

**Twin name:** `gitlab`

**Supports**

* GitLab REST API v4 routes for users, groups, namespaces, projects (by numeric ID or full path), repository branches, files, and commits, issues, merge requests, notes, discussions, pipelines, pipeline schedules, jobs, job artifacts, and project hooks.
* `glab api` style REST and GraphQL workflows, including a minimal GraphQL surface for `glab api graphql` calls.
* GitBeaker SDK-style calls, including package routes served outside `/api/v4` (`/projects/...`, `/groups/...`, `/packages/...`) and GitLab-shaped fallback responses for unmodeled endpoints on resolved projects.
* GitLab MCP-compatible JSON-RPC over `/api/v4/mcp` and `/mcp`, with tools for projects, issues, merge requests, files, and pipelines.
* Token authentication via `Authorization: Bearer ...`, `PRIVATE-TOKEN`, `JOB-TOKEN`, or `private_token` query parameters. Tokens match GitLab client expectations; no external authentication is performed.
* Admin endpoints to inspect and reseed state (`/admin/reset`, `/admin/state`, `/admin/clock`, `/admin/fidelity`) and a liveness check at `GET /healthz`.

**Known limitations**

* Users, groups, projects, branches, files, commits, issues, merge requests, pipelines, jobs, and hooks start empty unless seeded through config or scenario seeding, or created through API calls.
* The REST `/api/v4` surface, `glab` CLI compatibility, GitBeaker SDK compatibility, and the MCP JSON-RPC tools listed above are the fidelity target; other GitLab surfaces may be approximated or absent.
* Delete operations on seeded resources are non-destructive by design so SDK and CLI probes remain repeatable. To remove state, use the admin reset endpoint rather than relying on a `DELETE` to drop seeded entities.
* State is process-local and is discarded when the Twin Run ends.

**MCP tools:** `get_twin_catalog`, `provision_twins`, `start_url_validation`, `get_validation_results`.

See [Scenario seeding](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.