How to Upload Tableau Workbook to GitHub

Using version control for your Tableau dashboards might seem like overkill at first, but it can save you from a world of headaches down the road. This article will show you exactly how to use GitHub to back up, share, and track changes to your Tableau workbooks, step-by-step.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Why Bother with GitHub for Tableau, Anyway?

Tableau is a powerful visualization tool, but its built-in versioning capabilities (like a simple "Revert to Saved") are limited. Once you start collaborating with a team or maintaining critical dashboards, you'll quickly feel the need for something more robust. That's where Git and GitHub come in.

Think of GitHub as a safety net and a history book for your data visualizations. Here are the main benefits:

• Version Control: Have you ever made a "small change" that completely broke a dashboard, with no easy way to go back? GitHub allows you to save snapshots of your workbook at any point in time. If something goes wrong, you can simply revert to a previous, working version.
• Collaboration: GitHub simplifies teamwork. Multiple analysts can work on different aspects of a workbook. You can see who changed what and when, making it easier to merge updates and resolve conflicts without overwriting each other's work.
• Portfolio Building: A public GitHub profile is a fantastic way to showcase your Tableau skills. You can create a repository for your best work, allowing potential employers or clients to see not just the final product but also your development process.
• Backup & Documentation: It serves as a secure, off-site backup for your most important workbooks. You can also use the README.md file in your repository to document the purpose of the dashboard, data sources used, and any important notes - all in one place.

First, Which File Type: .twb or .twbx?

Before you upload anything, it's essential to understand the difference between Tableau's two main file types, as one is much better for GitHub than the other.

• A .twb (Tableau Workbook) file is an XML document. It contains all the instructions for building your visualizations - the sheets, dashboards, calculations, formatting, and connection details to your data sources. Because it's a text file, Git can easily track line-by-line changes. This is perfect for version control.
• A .twbx (Tableau Packaged Workbook) is essentially a zip file. It bundles the .twb file along with any local data sources (like Excel files or data extracts), custom shapes, and images. It's great for sharing a complete, self-contained dashboard with someone who doesn't have access to the original data sources. However, because it's a binary file, Git can't see the granular changes inside it. It can only tell you that the entire file has changed.

The verdict: For version control on GitHub, you should always work with the .twb file. A .twb file's XML structure allows Git to highlight exactly what has changed - whether you added a new calculated field, changed a color, or adjusted a filter.

How to Get the .twb File from a .twbx

If you only have a .twbx file, you can easily "unpackage" it to extract the .twb file and the associated data sources.

1. Make a copy of your .twbx file.
2. Change the file extension from .twbx to .zip.
3. Unzip the file. You will now see a folder containing the .twb file and sub-folders for your data, images, etc.

You can now add this .twb file and the related data files to your GitHub repository separately, giving you complete control over every piece of your project.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Setting Up Your GitHub Environment

If you're new to Git or GitHub, don't worry. The initial setup is straightforward, and you only have to do it once.

1. Create a GitHub Account and Install Git

First, if you don't already have one, sign up for a free account at GitHub.com.

Next, you’ll need to install Git on your computer. Git is the underlying version control software that powers GitHub. Go to the official Git downloads page and grab the installer for your operating system (Windows, Mac, or Linux). Follow the installation prompts, accepting the default settings is fine for most users.

2. Create a New Repository on GitHub

A repository (or "repo") is like a folder for your project on GitHub. This is where you'll store your Tableau workbook and any associated files.

1. On your GitHub homepage, click the "+" icon in the top right corner and select "New repository."
2. Give your repository a clear and descriptive name, like quarterly-sales-dashboard.
3. You can add a brief description explaining what the dashboard is for.
4. Choose whether to make the repository Public (visible to anyone) or Private (only visible to you and collaborators you invite). A public repo is great for a portfolio piece, while a private repo is best for internal company work.
5. Important: Check the box to "Add a .gitignore file." From the template dropdown, select "Tableau." This tells Git to ignore certain temporary or non-essential files generated by Tableau, keeping your repository clean.
6. Initialize the repository with a README file as well. This is good practice for documenting your project.
7. Click "Create repository."

Your repository is now live on GitHub! The next step is to connect it to your local machine.

Step-by-Step Guide: How to Upload Your Tableau Workbook

Now that the prep work is done, you can upload your workbook using a few simple command-line instructions. Open your command line application (Terminal on Mac/Linux, or Git Bash on Windows).

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Step 1: Clone the Repository to Your Computer

Cloning creates a local copy of your GitHub repository on your computer. Go to your repository's page on GitHub and click the green "Code" button. Copy the HTTPS URL provided.

In your command line, navigate to the directory where you want to store your project (e.g., cd Desktop/Projects) and then use the git clone command followed by the URL you just copied:

git clone https://github.com/YourUsername/quarterly-sales-dashboard.git

This will create a new folder on your computer named quarterly-sales-dashboard that is linked to your remote GitHub repository.

Step 2: Add Your Workbook Files to the Local Folder

Navigate into the newly created folder using the command line:

cd quarterly-sales-dashboard

Now, move or save your .twb file and any corresponding data files (e.g., CSV, Excel) directly into this folder. Keep your file structure organized. For example, you might create a data subfolder for your data sources and keep the .twb file in the main directory.

Step 3: Tell Git to Track Your New Files (Stage Changes)

Git doesn't automatically track files. You need to tell it which changes you want to include in your next saved version (your next "commit"). The command git add does this. It's also known as "staging" your files.

To add a specific file, you'd use its name. To add everything in the folder (which is common for the first upload), you can use a period:

git add .

This tells Git, "Get ready to commit all the new files and changes in this folder."

Step 4: Save a Snapshot of Your Files (Commit Changes)

A "commit" is a snapshot of your staged changes at a specific point in time. Each commit has a message that describes what was changed. Good commit messages are priceless - they become the historical log of your project.

Use the git commit command with the -m flag to add your message in-line:

git commit -m "Initial upload of the Q3 sales dashboard workbook and data source"

Your work is now saved to your local Git history.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Step 5: Push Your Local Changes to GitHub

The final step is to "push" your local commits up to the remote repository on GitHub, making them available online.

git push origin main

You may be prompted to enter your GitHub username and password (or a personal access token for added security).

That's it! If you refresh your repository page on GitHub, you'll see your Tableau workbook and other files proudly displayed.

Best Practices for Success

Getting your files on GitHub is just the start. Following a few best practices will make your life much easier in the long run.

• Write Clear Commit Messages: Instead of "updates," be specific. A message like "Feat: Added new YoY profit calculation to summary tab" makes it instantly clear what you did.
• Use Your .gitignore File: The Tableau .gitignore template is a great start, but you can customize it. If you decide to keep .twbx files in your folder but don't want to track them, add *.twbx to your .gitignore file.
• Commit Often: Don't wait until you've done hours of work. Made a significant new chart? Created a complex parameter? Commit it! This creates more granular restore points, making it easier to pinpoint issues and roll back small changes if needed.
• Never, Ever Commit Sensitive Data: This is a massive security risk. Be extremely careful not to include files with passwords, API keys, or personal identifying information (PII) in your commits. Data extracts containing sensitive information should also be excluded via your .gitignore file. Connect to databases using server-side credentials whenever possible rather than embedding them in the workbook.

Final Thoughts

Integrating GitHub into your Tableau workflow is a powerful way to add structure, security, and collaboration to your analytics process. Once you get the hang of the basic clone, add, commit, and push cycle, you can protect your work, track every change, and build a more reliable development process.

Manually tracking files and dealing with scattered data sources is one of the classic friction points in a daily reporting process. This is precisely why we built Graphed to be different. We streamline the entire workflow by letting you connect your data sources - like Google Analytics, Shopify, or Salesforce - directly. From there, you can use plain English to build real-time, interactive dashboards instantly, eliminating the need to save, manage, and upload static workbook files at all.