Automating Documentation Hosting and Deployment

In this lesson, you will learn how to bridge the gap between your local documentation and your stakeholders by automating the hosting and deployment of your dbt docs site.

Why Automate Documentation?

In previous lessons, we covered how to write high-quality descriptions and generate lineage graphs. However, documentation is only useful if it is accessible to your team. If you manually build the site and copy files to a server, the docs will quickly become outdated as your models evolve. Automating this process ensures that every time you merge code into main, your documentation site refreshes to reflect your latest data logic.

The Deployment Workflow

To automate this, you can integrate your documentation build into your CI/CD pipeline (e.g., GitHub Actions). The workflow follows three primary steps:

1. Generate: Use dbt docs generate to create the static HTML and JSON files representing your project's lineage and schema.
2. Upload: Use a CLI tool or script to sync these static files to a cloud storage bucket configured for web hosting (like AWS S3 with static website hosting enabled or GitHub Pages).
3. Notify: Post a comment in your pull request with a link to the updated site so reviewers can verify changes visually.

A simplified snippet for your CI YAML file might look like this:

jobs:
  deploy_docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: dbt docs generate
      - name: Deploy to S3
        run: aws s3 sync target/ s3://my-data-docs-bucket/ --delete

Ensuring Data Freshness

By tying this deployment to your merge event, you guarantee that the documentation site always matches the current state of your production environment. When a stakeholder opens the site, they are not looking at stale architecture—they are seeing the most recent transformation logic and source definitions exactly as they exist in your warehouse. This "docs-as-code" approach removes the friction of manual updates and builds trust with your data consumers.

Key Takeaway: Automating your documentation deployment as part of your CI/CD pipeline ensures that your lineage and metadata are always a single merge-request away from being perfectly up-to-date.