Skip to main content

​
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.
If you only import, a read-only token is enough; publishing requires a write scope — see Permissions below.

​
Requirements

​
Token setup

Create a Personal Access Token (Settings → Access Tokens) with the scope matching what you intend to do.

​
Permissions

For read-only use, a narrower alternative to read_api is read_repository + read_user.
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.
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 or SharePoint instead, where the write grant can be scoped more tightly.

​
What Cymph reads and writes

Commits are made to the branch you select, with the message Cymph: Publish playbook documentation.
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.

​
Publishing formats

GitLab accepts both documentation formats: Image blocks are omitted from the Markdown format.

​
Testing the connection

​
Limitations

GitLab is not available as a scheduled backup target — that is GitHub only.