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

# GitLab

> Projects, branches, commits, issues, merge requests, pipelines, labels, milestones, releases, and webhooks.

GitLab is included in Archal's environment catalog. Use it in a sandbox for projects, branches, commits, issues, merge requests, pipelines, labels, milestones, releases, and webhooks.

| | |
| - | - |
| Environment ID | `gitlab` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.gitlab` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

> [!NOTE]
>
> Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

* Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

## Curated starting states

List the five samples with `archal sample list gitlab`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

> [accordion] GitLab project baseline
>
> List one private project and update its description in the smallest corrected state.
>
> **Sample ID:** `gitlab.project-baseline.v1`
>
> **Category:** `minimal`
>
> **Starting state:** 2 records across `branches`: 1, `projects`: 1
>
> **Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`
>
> **First read:** `GET /api/v4/projects`. Expected result: HTTP 200.
>
> **Representative mutation:** `PUT /api/v4/projects/82857419`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "description": "Connector gateway with provider contract and retry regression coverage."
> }
> ```
>
> **Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show gitlab.project-baseline.v1 --raw > archal-gitlab-project-baseline.json
> archal state validate gitlab archal-gitlab-project-baseline.json
> archal session create gitlab \
>   --state gitlab=archal-gitlab-project-baseline.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show gitlab.project-baseline.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/gitlab/project-baseline/state.json` and is 2,771 bytes. The CLI verifies SHA-256 `726e75b351f1b641f497fc66a83879ea5c75bbaead0fd967a8364f6b204bb780` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] GitLab issue triage team
>
> Exercise one project, labels, milestone, member, issues, and notes for a small triage team.
>
> **Sample ID:** `gitlab.issue-triage-team.v1`
>
> **Category:** `small-team`
>
> **Starting state:** 13 records across `issueNotes`: 3, `issues`: 4, `labels`: 2, `milestones`: 1, `projectMembers`: 2, `projects`: 1
>
> **Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`
>
> **First read:** `GET /api/v4/projects/82857419/issues?state=all`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v4/projects/82857419/issues`. Expected result: HTTP 201.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "description": "Reproduce the connector timeout and retain the provider response before changing retry behavior.",
>   "labels": "connector,reliability",
>   "title": "Add provider timeout regression coverage"
> }
> ```
>
> **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show gitlab.issue-triage-team.v1 --raw > archal-gitlab-issue-triage-team.json
> archal state validate gitlab archal-gitlab-issue-triage-team.json
> archal session create gitlab \
>   --state gitlab=archal-gitlab-issue-triage-team.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show gitlab.issue-triage-team.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/gitlab/issue-triage-team/state.json` and is 11,097 bytes. The CLI verifies SHA-256 `44a3d26161597d11e8956cd852cc8d11c4e6100fb2127a839fb199004b3dce7f` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] GitLab corrected project corpus
>
> Cover the full reviewed GitLab corpus after removing only the later duplicate branch-id record.
>
> **Sample ID:** `gitlab.corrected-project-corpus.v1`
>
> **Category:** `populated`
>
> **Starting state:** 45 records across `branches`: 4, `commits`: 5, `deployKeys`: 1, `featureFlags`: 1, `featureFlagUserLists`: 1, `groupAccessTokens`: 1, `issueNotes`: 7, `issues`: 6, `labels`: 3, `mergeRequests`: 2, `milestones`: 1, `packageProtectionRules`: 1, `pipelineJobs`: 1, `pipelines`: 1, `projectAccessTokens`: 1, `projectMembers`: 2, `projects`: 2, `repoFiles`: 2, `snippets`: 2, `webhooks`: 1
>
> **Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`
>
> **First read:** `GET /api/v4/projects`. Expected result: HTTP 200.
>
> **Representative mutation:** `PUT /api/v4/projects/82857419`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "description": "Connector gateway with provider contract and retry regression coverage."
> }
> ```
>
> **Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show gitlab.corrected-project-corpus.v1 --raw > archal-gitlab-corrected-project-corpus.json
> archal state validate gitlab archal-gitlab-corrected-project-corpus.json
> archal session create gitlab \
>   --state gitlab=archal-gitlab-corrected-project-corpus.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show gitlab.corrected-project-corpus.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/gitlab/corrected-project-corpus/state.json` and is 135,716 bytes. The CLI verifies SHA-256 `4c56e4c4d713ba5dbcb621dac338fa20e3a78ccbb602860fc176ded996f28def` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] GitLab merge conflict
>
> Represent an open merge request whose source and target modify the same retained repository file.
>
> **Sample ID:** `gitlab.merge-conflict.v1`
>
> **Category:** `edge-case`
>
> **Starting state:** 8 records across `branches`: 2, `commits`: 2, `mergeRequests`: 1, `projects`: 1, `repoFiles`: 2
>
> **Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`
>
> **First read:** `GET /api/v4/projects/82857419/merge_requests/3`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v4/projects/82857419/merge_requests/3/notes`. Expected result: HTTP 201.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "body": "The conflict is still reproducible. Rebase on the retained target branch and rerun provider-contract tests."
> }
> ```
>
> **Expected diff:** changes include `mergeRequestNotes`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show gitlab.merge-conflict.v1 --raw > archal-gitlab-merge-conflict.json
> archal state validate gitlab archal-gitlab-merge-conflict.json
> archal session create gitlab \
>   --state gitlab=archal-gitlab-merge-conflict.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show gitlab.merge-conflict.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/gitlab/merge-conflict/state.json` and is 9,009 bytes. The CLI verifies SHA-256 `a4c80d73ac15620c31a9cf5efb7902f2971d5b5f7687dd13c9f2b6041f17ff08` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] GitLab merge request review workflow
>
> Start from an open merge request with retained branches, notes, pipeline, and job, then add and reset one review note.
>
> **Sample ID:** `gitlab.merge-request-review.v1`
>
> **Category:** `workflow`
>
> **Starting state:** 9 records across `branches`: 3, `issueNotes`: 1, `issues`: 1, `mergeRequests`: 1, `pipelineJobs`: 1, `pipelines`: 1, `projects`: 1
>
> **Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`
>
> **First read:** `GET /api/v4/projects/82857419/merge_requests/3`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v4/projects/82857419/merge_requests/3/notes`. Expected result: HTTP 201.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "body": "Review complete: keep the merge request open until the pipeline and connector contract checks are green."
> }
> ```
>
> **Expected diff:** changes include `mergeRequestNotes`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show gitlab.merge-request-review.v1 --raw > archal-gitlab-merge-request-review.json
> archal state validate gitlab archal-gitlab-merge-request-review.json
> archal session create gitlab \
>   --state gitlab=archal-gitlab-merge-request-review.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show gitlab.merge-request-review.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/gitlab/merge-request-review/state.json` and is 10,178 bytes. The CLI verifies SHA-256 `02085c5af43c2c1e4d1c3728db51d57b482303215e36133d25e99af9d9c211ca` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe gitlab`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate gitlab state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state.md) before replacing state in an existing sandbox.


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