Connect your project
An admin does these two steps once per project.
1. The BigQuery connection
Section titled “1. The BigQuery connection”Go to Settings → Project settings → Connections. You’ll need:
- A Google Cloud service account key (a JSON file) for a service account that can run queries and create tables in your project. At minimum the BigQuery Job User and BigQuery Data Editor roles on the dataset you will use.
- The Google Cloud project ID that holds your data.
- The dataset dbt should write its models to.
- The location of that dataset (for example
USorEU).
Press Test connection. It checks that the key is valid, that queries run, that the dataset is reachable in the right location, and that tables can be created. Fix anything that fails, then save.
The key is stored encrypted and is never shown again. One connection is shared by Build, Explore, Notebooks and Pipelines.
2. Choose where your code lives
Section titled “2. Choose where your code lives”Open Build. If nothing is set up, an admin chooses one of two options:
Managed repository
Section titled “Managed repository”We keep your dbt code, with full commit history, on the platform. There’s nothing to set up: you get a starter dbt project with a first commit, and can edit, commit and run straight away. You don’t need a GitHub account. (This is the same idea as a managed repository in dbt Cloud.)
- Commit saves a version in the managed history. There’s no Pull, because nothing else changes the code.
- Scheduled runs and Explore use the latest commit, exactly as they would with GitHub.
- You can move to GitHub whenever you like (below).
GitHub
Section titled “GitHub”Keep the project in your own GitHub repository:
- Choose Connect GitHub and sign in with GitHub. If the Reflective Data GitHub app is already installed on your account or organisation it is used (you choose one if there are several); otherwise you install it and select the repositories it may access. To give it more repositories later, open the app’s settings on GitHub (Configure), then come back to Build.
- Back in Build, pick the repository and, if you like, a branch (otherwise the repository’s default).
The platform checks that you really have access to the installation, so nobody can link repositories they don’t own. If the repository is empty, Build offers to create a starter dbt project in it.
Backing up a managed repository
Section titled “Backing up a managed repository”Download backup sits at the top of Build whenever the project uses a managed repository, and again at the start of Move to GitHub. It downloads everything in the repository as one .tar.gz: your files, the full commit history, and any changes you haven’t committed yet (build output such as target/ and logs/ is left out). Editors and admins can download it. To restore, unpack it: it is an ordinary git repository, so git log shows the history and you can push it to any remote.
Moving a managed repository to GitHub
Section titled “Moving a managed repository to GitHub”In a managed project an admin chooses Move to GitHub, installs the GitHub app if it isn’t yet, and picks an empty repository. Your code and its full history are copied into it and the project then works from GitHub, including Pull. A repository that already has code is refused, so nothing is overwritten.
Using a repository that already has code
Section titled “Using a repository that already has code”If you’d rather work from a repository that already holds your dbt project, choose it in the same Move to GitHub step. The platform tells you it isn’t empty and offers Discard managed code and use this repository. Confirm, and the managed code and notebooks are deleted (this can’t be undone) and the project works from the repository exactly as it is: nothing in the repository is changed. Afterwards, an admin presses Refresh models in Explore so it reads the new code.
Check it
Section titled “Check it”When both are done, the setup checklist on Home shows them as done, and you can run dbt from Build.