CI/CD Integration

Automate your documentation deployments with continuous integration. This guide covers setup for popular CI/CD platforms.

Connected a GitHub repo via the dashboard? You may not need CI at all. Projects linked through the Syntext GitHub App rebuild automatically on every push to the configured branch, and pull requests get preview builds — no workflow file required. The setups below are for repos without the App, or for pipelines that need extra steps (tests, codegen) before deploying.

GitHub Actions

The recommended approach for GitHub-hosted repositories.

Basic Workflow

Create .github/workflows/docs.yml:

name: Deploy Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
      
      - name: Install Syntext CLI
        run: curl -fsSL https://get.syntext.dev | sh
      
      - name: Deploy
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            stx deploy --preview
          else
            stx deploy
          fi
        env:
          SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}

With Caching

Speed up builds with dependency caching:

- name: Cache Syntext
  uses: actions/cache@v3
  with:
    path: ~/.syntext
    key: syntext-${{ runner.os }}-${{ hashFiles('syntext.json') }}
    restore-keys: |
      syntext-${{ runner.os }}-

- name: Cache Build
  uses: actions/cache@v3
  with:
    path: .syntext/cache
    key: build-${{ hashFiles('docs/**', 'syntext.json') }}

PR Preview Comments

Add preview URLs as PR comments:

- name: Deploy Preview
  id: preview
  if: github.event_name == 'pull_request'
  run: |
    URL=$(stx deploy --preview --json | jq -r '.url')
    echo "url=$URL" >> $GITHUB_OUTPUT
  env:
    SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}

- name: Comment PR
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v6
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '📚 Docs preview: ${{ steps.preview.outputs.url }}'
      })

GitLab CI

Create .gitlab-ci.yml:

stages:
  - deploy

deploy_docs:
  stage: deploy
  image: oven/bun:latest
  script:
    - curl -fsSL https://get.syntext.dev | sh
    - |
      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
        stx deploy --preview --branch "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
      else
        stx deploy
      fi
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    SYNTEXT_API_KEY: $SYNTEXT_API_KEY

With Caching

deploy_docs:
  cache:
    key: syntext-cache
    paths:
      - .syntext/cache
      - ~/.syntext

Bitbucket Pipelines

Create bitbucket-pipelines.yml:

image: oven/bun:latest

pipelines:
  branches:
    main:
      - step:
          name: Deploy Docs
          script:
            - curl -fsSL https://get.syntext.dev | sh
            - stx deploy
          caches:
            - syntext

  pull-requests:
    '**':
      - step:
          name: Preview Docs
          script:
            - curl -fsSL https://get.syntext.dev | sh
            - stx deploy --preview

definitions:
  caches:
    syntext: ~/.syntext

CircleCI

Create .circleci/config.yml:

version: 2.1

jobs:
  deploy:
    docker:
      - image: oven/bun:latest
    steps:
      - checkout
      - run:
          name: Install Syntext
          command: curl -fsSL https://get.syntext.dev | sh
      - run:
          name: Deploy
          command: stx deploy

workflows:
  deploy-docs:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Environment Variables

Required

Variable	Description
SYNTEXT_API_KEY	API key for authentication

Optional

Variable	Description
SYNTEXT_PROJECT_ID	Override project ID
SYNTEXT_ENV	production or staging

Getting Your API Key

1. Go to Syntext Dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy the key (shown only once)

Never commit API keys to your repository. Always use environment variables or secrets managers.

Monorepo Setup

For monorepos with docs in a subdirectory:

# GitHub Actions
- name: Deploy Docs
  working-directory: ./packages/docs
  run: stx deploy

Or with path filtering:

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'packages/docs/**'

Conditional Deployment

Deploy only when docs change:

- name: Check for docs changes
  id: changes
  run: |
    if git diff --name-only HEAD~1 | grep -E '^docs/|syntext\.config\.json'; then
      echo "deploy=true" >> $GITHUB_OUTPUT
    fi

- name: Deploy
  if: steps.changes.outputs.deploy == 'true'
  run: stx deploy

Deployment Status

Check deployment status programmatically:

stx status --json

Returns:

{
  "project": "my-docs",
  "status": "live",
  "url": "https://my-docs-docs.syntext.dev",
  "lastDeployment": "2024-01-15T12:34:56Z"
}