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

# GitLab

> Fetch playbooks and repository content from GitLab SaaS or a self-managed instance.

## What Cymph uses it for

Cymph connects to GitLab (SaaS or self-managed) for two purposes:

1. **Importing content** — fetches playbooks and repository content. *(read)*
2. **Publishing documentation** — commits a playbook's documentation into a repository as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks).

**If you only import, a read-only token is enough; publishing requires a write scope** — see [Permissions](#permissions) below.

## Requirements

| Field            | Description                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **Instance URL** | Base URL of your GitLab instance, e.g. `https://gitlab.com` or `https://gitlab.example.com` |
| **Token**        | A GitLab access token (see below)                                                           |

## Token setup

Create a [Personal Access Token](https://docs.gitlab.com/api/rest/authentication/) (**Settings → Access Tokens**) with the scope matching what you intend to do.

## Permissions

| If you want to                       | Scope      | Notes                                                                                |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------ |
| Import content only                  | `read_api` | Grants read access to projects, branches, and repository files                       |
| Import **and** publish documentation | `api`      | GitLab has no write-only file scope — committing files requires the full `api` scope |

<Tip>
  For read-only use, a narrower alternative to `read_api` is `read_repository` + `read_user`.
</Tip>

Beyond the token scope, the token's **user** must have a role on the target project that permits pushing — **Developer** or above. A protected target branch will reject the commit regardless of scope.

<Warning>
  `api` is a broad scope: it grants full read and write access to everything the token's user can reach, not just the project you publish to. If that is too much, keep the integration read-only with `read_api` and publish documentation to [GitHub](/integrations/content/github) or [SharePoint](/integrations/content/sharepoint) instead, where the write grant can be scoped more tightly.
</Warning>

## What Cymph reads and writes

| Purpose                       | GitLab API call                                      |
| ----------------------------- | ---------------------------------------------------- |
| Read a project's metadata     | `GET /api/v4/projects/{id}`                          |
| Commit playbook documentation | `POST /api/v4/projects/{id}/repository/files/{path}` |

Commits are made to the branch you select, with the message `Cymph: Publish playbook documentation`.

<Note>
  The publish call **creates** a file. Publishing to a path that already exists fails rather than overwriting, so re-publishing the same playbook to the same path and branch will error until the existing file is removed or a different path is chosen.
</Note>

## Publishing formats

GitLab accepts both documentation formats:

| Format          | What it contains                                                                  |
| --------------- | --------------------------------------------------------------------------------- |
| **Markdown**    | The playbook's documentation blocks, rendered as Markdown                         |
| **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image |

Image blocks are omitted from the Markdown format.

## Testing the connection

## Limitations

GitLab is not available as a scheduled backup target — that is [GitHub](/integrations/content/github) only.