Pushing your dbt project to GitHub

OrcheStack pulls your dbt project from a Git repository on every run. Here's how to get your project up on GitHub and connected to OrcheStack, assuming you've never done it before.

What you need

• A GitHub account (GitLab, Bitbucket, or any Git host also work — the steps are the same)
• Git installed locally — check with git --version. If missing, install from git-scm.com.
• A dbt project folder with a dbt_project.yml and at least one model under models/

Create the GitHub repository

1. Open github.com/new.
2. Name the repo something descriptive: acme-dbt, analytics-models, your-company-dbt.
3. Choose Private unless the whole world should read your SQL. Most teams pick private.
4. Don't tick "Initialize this repository with a README" — we'll push an existing project instead.
5. Click Create repository. GitHub shows you a URL; keep this tab open.

Initialise Git in your dbt project

Open a terminal and cd into your dbt project folder:

cd path/to/your-dbt-project
git init

If the folder already has a .git subfolder, skip the init.

The critical .gitignore

Before you commit anything, tell Git to ignore files that must never land in the repo:

# .gitignore
target/
dbt_packages/
logs/
profiles.yml
.user.yml
.env

Why each one matters:

• profiles.yml — contains your database password. Never commit.
• .env — contains secrets (API keys, tokens). Never commit.
• target/ — dbt's compiled SQL; regenerated on every run. Noise.
• dbt_packages/ — third-party package source; reinstalled from packages.yml on every run. Noise.
• logs/ — dbt run logs. Too large and machine-specific to version-control.

Save the file as .gitignore in the dbt project root.

First commit and push

Stage everything (respecting .gitignore) and commit:

git add .
git commit -m "Initial dbt project"

Connect the GitHub remote (replace with your repo URL from the tab you kept open):

git remote add origin https://github.com/your-org/your-dbt-repo.git
git branch -M main
git push -u origin main

Refresh GitHub — your files are now there.

Connect the repo to OrcheStack

Before pasting the URL into OrcheStack, take ten seconds to verify one thing inside your dbt project: the profile: value at the top of dbt_project.yml must match what you entered (or will enter) as the dbt project name in OrcheStack. OrcheStack uses that value as the top-level key when it generates profiles.yml; if they diverge, dbt fails to start with Could not find profile named 'X'.

# dbt_project.yml — first few lines
name: 'acme_analytics'
version: '1.0.0'
profile: 'acme_analytics'     # ← this is what OrcheStack needs to match

If the two values already match, you're good. If not, update profile: in dbt_project.yml OR update the project name field in OrcheStack — either way, make them identical.

Then, from your OrcheStack OrcheStack dashboard:

1. Click Services → dbt Core.
2. Click Edit config.
3. Confirm dbt project name matches your profile: value.
4. Paste the repo URL into dbt project Git repository:
   • HTTPS: https://github.com/your-org/your-dbt-repo.git
   • SSH: git@github.com:your-org/your-dbt-repo.git
5. Set Branch to track to main (or whichever branch holds production code).
6. Click Save & apply. OrcheStack will clone the repo into the dbt container.

From now on, every scheduled dbt run and every manual "Run dbt now" click pulls the latest commit from the tracked branch before executing.

Security — never commit secrets

Even with a private repo, commits are forever (in Git history). Habits that save you later:

• Never put passwords in dbt_project.yml or any SQL file. Use env_var() in profiles.yml and keep profiles.yml out of the repo entirely.
• Use .env for local development. Every developer gets their own .env with their own credentials. The .env file is in .gitignore.
• If you accidentally commit a secret: rotate it immediately (change the password in PostgreSQL, revoke the token, etc.). The leaked version lives in Git history forever — rotation is the only cure.

Private repos need a token

OrcheStack needs permission to clone a private repo. Two approaches:

HTTPS with a Personal Access Token (easiest)

1. On GitHub, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Give the token Contents: read-only access to just your dbt repo.
3. Copy the token.
4. In the OrcheStack dashboard → Services → dbt Core → Edit config, paste the token into Repo access token.

SSH with a deploy key (more secure)

1. On the OrcheStack host, run ssh-keygen -t ed25519 -f ./config/dbt/deploy_key -C "OrcheStack-dbt".
2. Copy the public key: cat ./config/dbt/deploy_key.pub.
3. On GitHub, go to the repo's Settings → Deploy keys → Add deploy key and paste it. Leave "Allow write access" unchecked — OrcheStack only reads.
4. In OrcheStack, switch the repo URL to SSH format (git@github.com:...) and save.