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
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
Variable
Description
SYNTEXT_API_KEY
A 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
Variable
Description
SYNTEXT_API_URL
API base URL (default https://api.syntext.dev)
The project comes from projectId in syntext.json โ write it once with stx connect and commit it.
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.