CI/CD Pipeline

Cartara runs directly within your CI/CD pipeline, allowing documentation to be automatically generated or updated whenever new code is merged into your main repository. In this section, we’ll walk through how to set that up

Create an API Key

1. Go to the API Keys section in the left-hand navigation menu.
2. Click the Create New API Key button located in the top-right corner of the page.
3. Enter a descriptive name for your new key.
4. Once generated, click the copy icon next to the name to securely copy the key to your clipboard.

Find Your External Space ID

The External Space ID tells Cartara where to place your generated documentation by linking it to the right internal space. For every repository, you’ll set an External Space ID in the CI/CD pipeline. All documentation created in that repository will be published to that space.

1. In the left-hand navigation menu, go to the Spaces section.
2. Select the space you want to use.
3. Click the ellipsis next to the space name, then choose Copy External Space ID from the menu to copy the ID to your clipboard.

CI/CD Pipeline

Add the code below to your gitlab-ci.yml file for GitLab, or to your .github/workflows folder if you're using GitHub. Make sure to replace API_KEY and SPACE_ID with the values obtained in the previous steps. It is strongly recommended that you use GitLab CI/CD variables or GitHub Actions secrets to securely protect your API key.

GitLab

stages:
- cartara

cartara:
  stage: cartara
  image: node:24
  only:
    - main
  before_script:
    - npm i cartara-cli
  script:
    - npx cartara apiKey=${API_KEY}
    - npx cartara spaceId=${SPACE_ID}
    - npx cartara dispatch

GitHub

name: Cartara

on:
  push:
    branches:
      - main

jobs:
  cartara:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup
        uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Install Cartara
        run: npm i cartara-cli

      - name: Run Cartara
        run: |
          npx cartara apiKey=${{ secrets.API_KEY }}
          npx cartara spaceId=${{ secrets.SPACE_ID }}
          npx cartara dispatch

And that’s it! Cartara will now automatically detect changes in tagged code and generate or update documentation as your code evolves.