/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Deployment GitHub Actions

GitHub Actions

Automatically deploy documentation on every push using GitHub Actions.

3 min read

Set up automatic documentation deployment with GitHub Actions. Deploy to production on merge to main, and create preview deployments for pull requests.

Basic Workflow

Create .github/workflows/docs.yml:

yaml
name: Deploy Documentation
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
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 }}

Setting Up Secrets

1.
Go to your repository on GitHub
2.
Navigate to Settings → Secrets and variables → Actions
3.
Click New repository secret
4.
Add SYNTEXT_API_KEY with your project API key — the workflow passes it to stx with --token
Warning

Never commit your API key. Always use GitHub Secrets.

PR Preview Comments

Post preview URLs as PR comments:

yaml
name: Deploy Documentation
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
pull-requests: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Syntext CLI
run: curl -fsSL https://get.syntext.dev | sh
- name: Deploy Preview
id: preview
if: github.event_name == 'pull_request'
run: |
OUTPUT=$(stx deploy --preview --branch "${{ github.head_ref }}" --json --token "$SYNTEXT_API_KEY")
URL=$(echo "$OUTPUT" | jq -r '.url')
echo "url=$URL" >> $GITHUB_OUTPUT
env:
SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}
- name: Comment on 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: `📚 **Documentation Preview**\n\n${{ steps.preview.outputs.url }}`
})
- name: Deploy Production
if: github.event_name == 'push'
run: stx deploy --token "$SYNTEXT_API_KEY"
env:
SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}

Conditional Deployment

Only deploy when docs change:

yaml
on:
push:
branches: [main]
paths:
- 'docs/**'
- 'syntext.json'
- 'openapi.json'

Monorepo Setup

For monorepos with docs in a subdirectory:

yaml
jobs:
deploy:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ./packages/docs
steps:
- name: Checkout
uses: actions/checkout@v4
# ... rest of workflow

Multiple Documentation Sites

Deploy multiple docs sites from one repo:

yaml
jobs:
deploy-api-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: curl -fsSL https://get.syntext.dev | sh
- run: stx deploy --token "$SYNTEXT_API_KEY"
working-directory: ./docs/api
env:
SYNTEXT_API_KEY: ${{ secrets.API_DOCS_KEY }}
deploy-user-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: curl -fsSL https://get.syntext.dev | sh
- run: stx deploy --token "$SYNTEXT_API_KEY"
working-directory: ./docs/users
env:
SYNTEXT_API_KEY: ${{ secrets.USER_DOCS_KEY }}

Deployment Status Check

Add deployment status as a required check:

1.
Go to Settings → Branches
2.
Add branch protection rule for main
3.
Enable Require status checks to pass
4.
Select the deployment job

Troubleshooting

Build Fails with "No syntext.json found in this directory."

Ensure syntext.json exists in the working directory (or pass --dir):

yaml
- run: ls -la
- run: cat syntext.json

Authentication Error

Verify your API key is set correctly:

yaml
- run: echo "API key length: ${#SYNTEXT_API_KEY}"
env:
SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext