dbt documentation is a powerful asset for any data team. It provides a clear, interactive map of your data models, sources, and tests. But let’s be honest, for that documentation to be useful, it must be up to date and easily accessible. Keeping your dbt docs fresh after every model change can be a tedious chore that often falls by the wayside.

What if you could set up a system that automatically publishes your dbt docs to a free, shareable website every time you update your project?

In this guide, we’ll show you exactly how to do that. We’ll walk through a simple, automated workflow to publish your dbt docs to GitHub Pages. The best part? You can have the entire system up and running in about 15 minutes. Let’s build a solution that makes your documentation a living, breathing resource, not a forgotten artifact.

Before we dive into the “how,” let’s quickly cover the “why.” Automating your documentation isn’t just a technical convenience; it’s a strategic move that fundamentally improves how your team and your stakeholders interact with data.

The Friction of Manual Documentation

A manual documentation process can lead to several downstream problems:

• Outdated Information: It’s easy for developers to forget to run the commands and upload the new files. Stakeholders might then make decisions based on old or incorrect data definitions.
• Low Adoption: For business users to adopt the documentation, it needs to be easy to find and trustworthy. Otherwise, they’ll stop using it and revert to asking the data team the same questions repeatedly.
• Manual Overhead: Automation frees up the data team from spending valuable time on a repetitive, low-impact task. In our client projects, we’ve found this simple automation saves upwards of 5 hours per month in developer time.

Key Benefits of an Automated Workflow

Implementing a “set it and forget it” pipeline with GitHub Actions and GitHub Pages delivers immediate and lasting value.

• A Single Source of Truth: Your documentation site is always perfectly in sync with your main branch. When a model is updated in your dbt project, its documentation is automatically updated for everyone to see.
• Empower Stakeholders: An accessible, public (or private) URL allows business analysts, product managers, and other stakeholders to self-serve. They can explore data lineage, understand column definitions, and trust that what they’re seeing is accurate.
• Improve Data Team Efficiency: By removing a manual step from your workflow, you free up engineers to focus on what they do best: building robust, reliable data models. This small investment in automation pays dividends in productivity and focus.

This tutorial is designed to be fast and straightforward. To follow along, you’ll need just a few things in place:

• A dbt Core project: Your project should be hosted in a GitHub repository. This guide is tailored for dbt Core users who manage their own deployment environment. While dbt Cloud has its own integrated documentation hosting, this solution is perfect for teams leveraging the flexibility of dbt Core.
• Repository Permissions: You’ll need admin or maintainer permissions for the repository to manage settings and configure GitHub Actions. This allows you to enable GitHub Pages and create the workflow file.

That’s it. If you have a dbt project in a GitHub repo, you’re ready to go.

Now, let’s get to the main event. We’ll break this down into four simple steps that will take you from manual chaos to automated bliss in minutes.

Step 1: Generate Your dbt Documentation Locally (2 minutes)

First, let’s ensure you can generate the documentation on your own machine. This confirms your dbt project is set up correctly and helps you understand what files we’ll be automating.

Navigate to your dbt project’s root directory in your terminal and run the core documentation command:

dbt docs generate

This command compiles your project and generates a set of static HTML and JSON files that make up your documentation site. Once it completes, you’ll find these files inside the target/ directory. The key files are:

• index.html: The main entry point for your documentation site.
• manifest.json: A machine-readable JSON file containing information about your dbt project resources.
• catalog.json: A JSON file with metadata about your database objects.

You can open the target/index.html file in a web browser to see the local version of your documentation. Our goal is to get this exact site onto a public URL.

Step 2: Configure Your GitHub Repository for GitHub Pages (3 minutes)

Next, we need to tell GitHub where to find the files for your documentation website. We will configure it to serve files from a specific branch called gh-pages. While this branch doesn’t exist yet, our automation will create and populate it for us later.

1. In your GitHub repository, go to the Settings tab.
2. In the left sidebar, click on Pages.
3. Under the “Build and deployment” section, for the Source, select Deploy from a branch.
4. Under “Branch,” select gh-pages and keep the folder as / (root). If gh-pages isn’t an option yet, don’t worry. You can type it in, or simply wait for our workflow to create it in the next step.
5. Click Save.

Your repository is now ready to host a site. All we need to do is push our documentation files to that gh-pages branch.

Step 3: Create the GitHub Actions Workflow for Automation (8 minutes)

This is the heart of our automation. We will create a GitHub Actions workflow. This is a small YAML file that tells GitHub what commands to run whenever we push code to our main branch.

1. In your code editor, create a new directory structure in your dbt project’s root: .github/workflows/.
2. Inside that workflows directory, create a new file named publish-docs.yml.
3. Copy and paste the following code into publish-docs.yml. Here’s the exact YAML configuration we recommend for a robust setup:

Breaking Down the Workflow File

Let’s quickly review what each part of this file does:

• on: push: branches: [“main”]: This is the trigger. The workflow will run automatically every time someone pushes a commit to the main branch.
• jobs: build-and-deploy-docs: This defines the sequence of tasks the workflow will execute.
• actions/checkout@v3: This is a standard action that checks out your repository’s code so the workflow can access it.
• Set up dbt profile: The dbt docs generate command needs a valid profiles.yml file to run, even though it doesn’t need to connect to your warehouse. This step creates a minimal, temporary profile using DuckDB to satisfy the requirement without exposing any credentials.
• Set up Python & Install dbt: These steps prepare the environment by installing Python and the necessary dbt packages.
• dbt docs generate: This is the same command we ran locally. It builds the static documentation site and places it in the target/ directory.
• peaceiris/actions-gh-pages@v3: This is the magic step. This popular third-party action takes the contents of a specified directory (publish_dir: ./target) and pushes them to the gh-pages branch, effectively deploying our site.

Step 4: Commit, Push, and Verify Your Live dbt Docs (2 minutes)

Now for the final step. All that’s left is to commit our new workflow file and push it to GitHub.

1. Save the publish-docs.yml file.
2. In your terminal, add the new file to git, commit it, and push it to your main branch.

As soon as you push this commit, GitHub will automatically detect the new workflow file and trigger a run.

• Verify the Workflow: Go to the Actions tab in your GitHub repository. You should see your “Publish dbt Docs” workflow running. Click on it to see the logs for each step.
• Find Your Live URL: Once the workflow completes successfully (it should take a minute or two), navigate back to Settings > Pages. You will now see a message at the top saying, “Your site is live at https://<your-username>.github.io/<your-repo-name>/“.

Click the link, and you should see your fully interactive dbt documentation site, live and accessible to anyone you share the URL with.

Congratulations! You’ve built a robust, automated pipeline for your dbt documentation. Here are a few tips to enhance it further.

Securing Your dbt Docs

By default, GitHub Pages sites on public repositories are public. If your documentation contains sensitive information, you should host it in a private repository. You can then manage access control through GitHub’s settings, ensuring only authorized team members can view the documentation.

Custom Domains

Want a more professional URL? You can easily configure a custom domain (e.g., dbt-docs.yourcompany.com) for your GitHub Pages site. This involves adding a CNAME file to your repository and updating DNS records with your domain provider.

Handling Multiple Environments (Dev/Prod)

For more advanced setups, you might want to publish documentation for different dbt targets (e.g., dev vs. prod). You can adapt the workflow to handle this by using different branches as triggers or by passing variables into your dbt commands to change the target.

Automating your documentation is a fantastic first step toward building a well-oiled data machine. It solves a specific, high-visibility problem and introduces your team to the power of CI/CD. But this is just the beginning. The same principles can be applied to automate testing, deployments, and data quality monitoring across your entire data stack.

At Stellans, we help teams build these kinds of robust, end-to-end automated systems. We move beyond simple tasks and help you implement a full-stack data platform where reliability and efficiency are built-in, not bolted on.

Ready to automate more than just your documentation? Learn more about our Data Engineering services.

In just a few short steps, you’ve transformed your dbt documentation from a static, quickly outdated artifact into a dynamic, self-updating resource. By leveraging the power of GitHub Actions, you’ve created a seamless pipeline that ensures your entire organization has access to a single source of truth for your data. This small investment in automation not only improves efficiency but also fosters a culture of data literacy and trust, empowering everyone to make better, data-informed decisions.

How do I host dbt docs on GitHub Pages?

You can host dbt docs on GitHub Pages by first generating the static site using the dbt docs generate command. Then, use a GitHub Actions workflow to automatically deploy the output files from your target/ folder to a dedicated gh-pages branch in your repository, which GitHub Pages will then serve as a website.

Can I automate dbt documentation deployment?

Yes, you can fully automate the deployment of dbt documentation using a CI/CD tool like GitHub Actions. By creating a simple workflow YAML file in your repository, you can configure an action that triggers on every push to your main branch, automatically generates the latest docs, and publishes them to a hosting service like GitHub Pages.

Can I make my dbt docs private?

Yes. If your GitHub repository is private, your associated GitHub Pages site can also be restricted. You can manage access through your repository’s settings, allowing only authenticated members of your organization to view the deployed documentation site.

• dbt Labs Official Documentation: https://docs.getdbt.com/
• GitHub’s Official Documentation for Actions: https://docs.github.com/en/actions
• GitHub’s Official Documentation for Pages: https://docs.github.com/en/pages