Choosing the Right Build Trigger for ReadTheDocs: Webhooks vs. Manual Builds

Why Build Triggers Matter

When you host documentation on ReadTheDocs (RTD), the way your docs are rebuilt can make or break your release workflow. A silent build failure or an out‑of‑sync version can cause confusion for users and developers alike. The core decision is whether to let RTD rebuild automatically on every push via a webhook, or to trigger builds manually (or via CI) when you’re ready. This blog walks through the concrete trade‑offs and shows you a minimal configuration that works out of the box.

Automatic Builds via Webhooks

RTD integrates with GitHub, GitLab, and Bitbucket. When you enable the "Build on push" option, RTD registers a webhook that fires on every push to the repository. The webhook sends a JSON payload to RTD’s build API, which then pulls the latest commit and starts a build.

Benefits

• Instant feedback: every commit triggers a fresh build, so you see documentation errors as early as possible.
• Versioned documentation: each commit becomes a new version, automatically available on the RTD UI.
• Zero‑maintenance: no need to maintain a separate CI pipeline for docs.

Limitations

• Build minutes are limited on the free tier (typically 20 hours/month). Heavy projects can hit the ceiling quickly.
• Complex projects with large assets or many dependencies may fail silently if the build environment lacks required packages.
• Debugging a build failure requires inspecting RTD’s build logs, which can be less convenient than a local CI log.

Manual or CI‑Triggered Builds

If you prefer tighter control, you can disable the automatic build option and trigger builds via the RTD API or a CI system like GitHub Actions. For example, a minimal GitHub Actions workflow that builds docs only on the "main" branch:

name: Build Docs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trigger RTD build
        run: |
          curl -X POST \
            -H "Authorization: Token ${{ secrets.RTD_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"commit": "${{ github.sha }}"}' \
            https://readthedocs.org/api/v3/projects/your-project-name/builds/

Replace your-project-name with your RTD project slug. This approach gives you:

• Control over when builds happen (e.g., only on release tags).
• Ability to run pre‑build checks locally or in CI before notifying RTD.
• Reduced build minutes consumption on RTD.

Concrete Example: A Minimal Sphinx Project

Below is a step‑by‑step guide to set up a Sphinx project that uses RTD’s automatic build trigger and verifies the build.

1. Repository Setup
   • Create a new GitHub repo called demo-docs.
   • Add a docs/ directory with a conf.py and index.rst.
   • Commit and push to GitHub.
2. Enable RTD Project
   • Log into ReadTheDocs and click "Import a Project".
   • Choose the GitHub repo and accept the default settings.
   • Under "Advanced Settings", ensure "Build on push" is checked.
3. Check Build Status
   • Navigate to the RTD project page; you should see a green "Building" indicator.
   • After the build completes, click the version link (e.g., master) to view the rendered docs.
   • Verify that the index.html contains the expected heading.
4. Test Version Switching
   • Make a new commit that adds a file docs/extra.rst.
   • Push to GitHub; a new build starts automatically.
   • On RTD, you’ll see a new version (e.g., commit‑abcd1234) that includes extra.html.
5. Rollback a Bad Build
   • If the new build fails, click the version name and select "Rollback" to revert to the previous successful build.
   • RTD will create a new build from the last good commit.

Trade‑Offs and When to Pick Each Approach

Choose automatic webhooks if:

• Your docs are lightweight and you want immediate feedback.
• You prefer a hands‑off approach without maintaining CI.
• You’re comfortable with RTD’s rate limits.

Choose manual/CI triggers if:

• Builds are expensive in terms of compute time (e.g., large PDFs or many images).
• You need to run tests or linting before allowing a build.
• You want to control the exact commit that is built (e.g., only release tags).
• You need to avoid the free tier build‑minute ceiling.

Actionable Checklist

• Decide on a build trigger strategy based on project size and team workflow.
• Enable the corresponding setting in RTD’s project configuration.
• If using CI, secure an RTD API token and store it as a secret.
• Implement basic build‑time checks locally (e.g., make html).
• Regularly monitor RTD’s build dashboard for failures and review logs.

With these steps, you’ll have a reliable, reproducible documentation build pipeline that balances speed, control, and cost.