GitLab Sync

Theneo offers seamless synchronization with GitLab repositories, enabling automatic pushing of your API specifications or entire documentation folders to your Theneo workspace. This guide walks you through the steps to configure GitLab CI/CD for Theneo sync.

Before starting, make sure you have:

• A GitLab repository where you manage your API specs or documentation.
• Your Theneo API Key.
• The following Theneo configuration variables set in your GitLab CI/CD settings:
• THENEO_API_KEY: Your Theneo API token, used for authentication, can be found in your Theneo profile settings.
• THENEO_PROJECT_SLUG: Your project's unique identifier in Theneo, accessible under project settings.
• THENEO_WORKSPACE_SLUG: Project workspace slug to import documentation under specific workspace, accessible under project settings.
• THENEO_VERSION_SLUG: Project version slug to import documentation under a specific version, otherwise default version will be used.
• THENEO_FILE_PATH : The path to your API documentation file within the repository (for API spec import).
• Folder_PATH : The path to your documentation folder within the repository (for folder import).

Setup Instructions

You can configure the sync by either editing your existing .gitlab-ci.yml file or creating a new one in your repository.

Import API Specs Only

To push a single OpenAPI spec file to Theneo, use the following .gitlab-ci.yml 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 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

You can also specify how Theneo handles incoming changes using the --import-type option:

• overwrite – Replaces the existing documentation with the new specification entirely.
• merge (beta) – Attempts to combine new content with existing documentation. May append or blend content based on:
• PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new
• SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old
• endpoints – Adds new spec endpoints into a separate section for manual arrangement later in the editor.

Import an Entire Folder

To push an entire folder to Theneo, use this alternative 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 OpenAPI spec to Theneo..."
    - |
      theneo import \
        --project $THENEO_PROJECT_SLUG \
        --workspace $THENEO_WORKSPACE_SLUG \
        --projectVersion $THENEO_VERSION_SLUG \
        --publish \
        --dir $Folder_PATH \