GitLab Sync

Theneo syncs seamlessly with GitLab, automatically pushing your API specs or entire documentation folders to your workspace on every pipeline run. Here’s how to wire up GitLab CI/CD.

Before you start

Make sure you have a GitLab repository, your Theneo API key, and the following variables set in your GitLab CI/CD settings:

• THENEO_API_KEY — your Theneo API token (from your profile settings).
• THENEO_PROJECT_SLUG — your project’s unique identifier in Theneo.
• THENEO_WORKSPACE_SLUG — the workspace to import into.
• THENEO_VERSION_SLUG — the version to import to (defaults to the default version).
• THENEO_FILE_PATH — path to your API spec file (for spec imports).
• Folder_PATH — path to your documentation folder (for folder imports).

Import API specs only

Push a single OpenAPI spec to Theneo with this .gitlab-ci.yml:

image: node:22
stages:
push-to-theneo
push-openapi-to-theneo:
stage: push-to-theneo
script:
- npm install -g @theneo/cli@latest
- echo “Logging in to Theneo…”
- theneo login --token $THENEO_API_KEY
- echo “Listing Theneo projects…”
- theneo project list
- echo “Importing OpenAPI spec to Theneo…”
- |
theneo project import 
–project $THENEO_PROJECT_SLUG 
–workspace $THENEO_WORKSPACE_SLUG 
–projectVersion $THENEO_VERSION_SLUG 
–publish 
–file $THENEO_FILE_PATH 
–import-type overwrite

Control how Theneo handles changes with --import-type:

• overwrite — replace the existing documentation entirely.
• merge (beta) — combine new content with existing docs, using PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new and SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old.
• endpoints — add new endpoints into a separate section for manual arrangement.

Import an entire folder

To push a whole folder, swap in this script:

image: node:22
stages:
push-to-theneo
push-openapi-to-theneo:
stage: push-to-theneo
script:
- npm install -g @theneo/cli@latest
- echo “Logging in to Theneo…”
- theneo login --token $THENEO_API_KEY
- echo “Listing Theneo projects…”
- theneo project list
- echo “Importing documentation folder to Theneo…”
- |
theneo import 
–project $THENEO_PROJECT_SLUG 
–workspace $THENEO_WORKSPACE_SLUG 
–projectVersion $THENEO_VERSION_SLUG 
–publish 
–dir $Folder_PATH

• Keep @theneo/cli up to date to benefit from the latest features and fixes.
• The --publish flag makes your imported content live automatically.