/Docs
Search docs or ask a questionโŒ˜K
DocsAgent
Changelog
Guides CI/CD Integration

CI/CD Integration

Automate documentation deployments with GitHub Actions, GitLab CI, and other CI/CD platforms.

4 min read

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

Note

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:

yaml
name: Deploy Docs
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- 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 --branch "${{ github.head_ref }}" --token "$SYNTEXT_API_KEY"
else
stx deploy --token "$SYNTEXT_API_KEY"
fi
env:
SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}

PR Preview Comments

Add preview URLs as PR comments:

yaml
- name: Deploy Preview
id: preview
if: github.event_name == 'pull_request'
run: |
URL=$(stx deploy --preview --branch "${{ github.head_ref }}" --json --token "$SYNTEXT_API_KEY" | 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:

yaml
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" --token "$SYNTEXT_API_KEY"
else
stx deploy --token "$SYNTEXT_API_KEY"
fi
rules:
- if: $CI_COMMIT_BRANCH == "main"
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
SYNTEXT_API_KEY: $SYNTEXT_API_KEY

Bitbucket Pipelines

Create bitbucket-pipelines.yml:

yaml
image: oven/bun:latest
pipelines:
branches:
main:
- step:
name: Deploy Docs
script:
- curl -fsSL https://get.syntext.dev | sh
- stx deploy --token "$SYNTEXT_API_KEY"
pull-requests:
'**':
- step:
name: Preview Docs
script:
- curl -fsSL https://get.syntext.dev | sh
- stx deploy --preview --branch "$BITBUCKET_BRANCH" --token "$SYNTEXT_API_KEY"

Pass --branch on every preview deploy: without it, all previews share one address (preview--<slug>-docs.syntext.dev) and overwrite each other.

CircleCI

Create .circleci/config.yml:

yaml
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 --token "$SYNTEXT_API_KEY"
workflows:
deploy-docs:
jobs:
- deploy:
filters:
branches:
only: main

Environment Variables

Required

VariableDescription
SYNTEXT_API_KEYA project API key, kept in your CI provider's secrets. The examples pass it to stx with --token โ€” the CLI does not read it from the environment on its own

Optional

VariableDescription
SYNTEXT_API_URLAPI base URL (default https://api.syntext.dev)

The project comes from projectId in syntext.json โ€” write it once with stx connect and commit it.

Getting Your API Key

1.
Open your project in the Syntext dashboard
2.
Navigate to Settings โ€บ API keys
3.
Under Create a key, enter a Name, choose an Expires option and a Scope โ€” Build & deploy is enough for CI (prefer the narrowest scope; Full access can manage settings and other keys)
4.
Click Create key
5.
Copy the key from the banner โ€” this is the only time the full key is shown, and you must confirm you've saved it before dismissing it
Warning

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

Monorepo Setup

For monorepos with docs in a subdirectory:

yaml
# GitHub Actions
- name: Deploy Docs
working-directory: ./packages/docs
run: stx deploy --token "$SYNTEXT_API_KEY"

Or with path filtering:

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

Conditional Deployment

Deploy only when docs change:

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

Deployment Status

stx deploy waits for the build and exits non-zero if it fails, so the CI step's own status is the deployment status. With --json, it prints the result:

json
{
"success": true,
"buildId": "9f8e7d6c-โ€ฆ",
"url": "https://my-docs-docs.syntext.dev",
"files": 42,
"preview": false,
"duration": 4523
}

To check a build later, call Get Build with its buildId.

Was this page helpful? Yes No
Product
Resources
Company
ยฉ 2026 SyntextBuilt with Syntext