GitHub Actions

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:

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: 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 }}

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 API key

Never commit your API key. Always use GitHub Secrets.

With Caching

Speed up builds with caching:

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: Setup Bun
        uses: oven-sh/setup-bun@v1
      
      - name: Cache Syntext
        uses: actions/cache@v3
        with:
          path: |
            ~/.syntext
            .syntext/cache
          key: syntext-${{ runner.os }}-${{ hashFiles('syntext.json', 'docs/**') }}
          restore-keys: |
            syntext-${{ runner.os }}-
      
      - 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 }}

PR Preview Comments

Post preview URLs as PR comments:

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: Setup Bun
        uses: oven-sh/setup-bun@v1
      
      - 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 --json)
          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
        env:
          SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}

Conditional Deployment

Only deploy when docs change:

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

Monorepo Setup

For monorepos with docs in a subdirectory:

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:

jobs:
  deploy-api-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://get.syntext.dev | sh
      - run: stx deploy
        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
        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 config found"

Ensure syntext.json exists in the working directory:

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

Authentication Error

Verify your API key is set correctly:

- run: echo "API key length: ${#SYNTEXT_API_KEY}"
  env:
    SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}