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.