Skip to content

Commit 58088bd

Browse files
doriwilsondoriwilson
authored
Merge pull request #71 from DataRecce/docs/connect-git-warehouse
docs: add connect-git and update connect-to-warehouse
2 parents dfff596 + c674471 commit 58088bd

13 files changed

Lines changed: 211 additions & 211 deletions

File tree

‎docs/2-getting-started/connect-git.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Connect Your Repository
2+
3+
**Goal:** Connect your GitHub or GitLab repository to Recce Cloud for automated PR data review.
4+
5+
Recce Cloud supports GitHub and GitLab. Using a different provider? Contact us at support@reccehq.com.
6+
7+
## Prerequisites
8+
9+
- [x] Recce Cloud account (free trial at cloud.reccehq.com)
10+
- [x] Repository admin access (required to authorize app installation)
11+
- [x] dbt project in the repository
12+
13+
## How It Works
14+
15+
When you connect a Git provider, Recce Cloud maps your setup:
16+
17+
| Git Provider | Recce Cloud |
18+
|--------------|-------------|
19+
| Organization | Organization |
20+
| Repository | Project |
21+
22+
Every Recce Cloud account starts with one organization and one project. When you connect your Git provider, you select which organization and repository to link.
23+
24+
**Monorepo support:** If you have multiple dbt projects in one repository, you can create multiple Recce Cloud projects that connect to the same repo.
25+
<!-- TODO: add link to monorepo section -->
26+
27+
## Connect GitHub
28+
29+
### 1. Authorize the Recce GitHub App
30+
31+
Navigate to Settings → Git Provider in Recce Cloud. Click **Connect GitHub**.
32+
33+
**Expected result:** GitHub authorization page opens.
34+
35+
### 2. Select Organization and Repository
36+
37+
Choose which GitHub organization to connect. This becomes your Recce Cloud organization.
38+
39+
Then select the repository containing your dbt project. This becomes your Recce Cloud project.
40+
41+
**Expected result:** Repository connected. Your Recce Cloud project is ready to use.
42+
43+
![alt text](../assets/images/2-getting-started/connect-github.png){: .shadow}
44+
45+
## Connect GitLab
46+
47+
GitLab uses Personal Access Tokens (PAT) instead of OAuth.
48+
49+
### 1. Create a Personal Access Token
50+
51+
In GitLab: User Settings → Access Tokens → Add new token.
52+
53+
**Required scopes:**
54+
55+
- `api` - Full access (required for PR comments)
56+
- `read_api` - Read-only alternative (limited functionality)
57+
58+
**Expected result:** Token string displayed (copy immediately).
59+
60+
### 2. Add Token to Recce Cloud
61+
62+
Navigate to Settings → Git Provider. Select GitLab, paste token.
63+
64+
## Verify Success
65+
66+
In Recce Cloud, navigate to your repository. You should see:
67+
68+
- Connection status: "Connected"
69+
- Organization Project is linked to a git repository
70+
71+
![alt text](../assets/images/2-getting-started/connect-gitlab.png){: .shadow}
72+
![alt text](../assets/images/2-getting-started/org-projects.png){: .shadow}
73+
74+
## Troubleshooting
75+
76+
| Issue | Solution |
77+
| --- | --- |
78+
| Repository not found | Ensure proper permissions are granted (GitLab: token access, GitHub: app authorized) |
79+
| Invalid token (GitLab) | Generate new token with `api` scope |
80+
| Cannot post PR comments (GitLab) | Regenerate token with `api` scope instead of `read_api` |
81+
82+
## Next Steps
83+
84+
- [Connect Data Warehouse](connect-to-warehouse.md)
85+
- [Add Recce to CI/CD](../7-cicd/ci-cd-getting-started.md)

‎docs/2-getting-started/connect-to-warehouse.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Connect Data Warehouse
2+
3+
**Goal:** Connect your data warehouse to Recce Cloud to enable data diffing on PRs.
4+
5+
Recce Cloud supports **[Snowflake](#connect-snowflake), [Databricks](#connect-databricks), [BigQuery](#connect-bigquery), and [Redshift](connect-redshift)**. Using a different warehouse? Contact us at support@reccehq.com.
6+
7+
## Prerequisites
8+
9+
- [x] Warehouse credentials with read access
10+
- [x] Network access configured (IP whitelisting if required)
11+
12+
## Security
13+
14+
Recce Cloud queries your warehouse directly to compare Base and Current environments. Recce encrypts and stores credentials securely. Read-only access is sufficient for all data diffing features.
15+
16+
## Connect Snowflake
17+
18+
### Option 1: Username/Password
19+
20+
| Field | Description | Example |
21+
|-------|-------------|---------|
22+
| Account | Snowflake account identifier | `xxxxxx.us-central1.gcp` |
23+
| Username | Database username | `MY_USER` |
24+
| Password | Database password | `my_password` |
25+
| Role | Role with read access | `ANALYST_ROLE` |
26+
| Warehouse | Compute warehouse name | `WH_LOAD` |
27+
28+
### Option 2: Key Pair Authentication
29+
30+
| Field | Description | Example |
31+
|-------|-------------|---------|
32+
| Account | Snowflake account identifier | `xxxxxx.us-central1.gcp` |
33+
| Username | Service account username | `MY_USER` |
34+
| Private Key | PEM-formatted private key | `-----BEGIN RSA PRIVATE KEY-----...` |
35+
| Passphrase | Key passphrase (if encrypted) | `my_passphrase` |
36+
| Role | Role with read access | `ANALYST_ROLE` |
37+
| Warehouse | Compute warehouse name | `WH_LOAD` |
38+
39+
## Connect Databricks
40+
41+
### Option 1: Personal Access Token
42+
43+
| Field | Description | Example |
44+
|-------|-------------|---------|
45+
| Host | Workspace URL | `adb-1234567890123456.7.azuredatabricks.net` |
46+
| HTTP Path | SQL warehouse path | `/sql/1.0/warehouses/abc123def456` |
47+
| Token | Personal access token | `dapiXXXXXXXXXXXXXXXXXXXXXXX` |
48+
| Catalog | Unity Catalog name (optional) | `my_catalog` |
49+
50+
### Option 2: OAuth (M2M)
51+
52+
| Field | Description | Example |
53+
|-------|-------------|---------|
54+
| Host | Workspace URL | `adb-1234567890123456.7.azuredatabricks.net` |
55+
| HTTP Path | SQL warehouse path | `/sql/1.0/warehouses/abc123def456` |
56+
| Client ID | Service principal client ID | `12345678-1234-1234-1234-123456789012` |
57+
| Client Secret | Service principal secret | `dose1234567890abcdef` |
58+
| Catalog | Unity Catalog name (optional) | `my_catalog` |
59+
60+
61+
> **Note**: OAuth M2M is auto-enabled in Databricks accounts. For setup details, see [dbt Databricks setup](https://docs.getdbt.com/docs/core/connect-data-platform/databricks-setup#oauth-machine-to-machine-m2m-authentication).
62+
63+
## Connect BigQuery
64+
65+
| Field | Description | Example |
66+
|-------|-------------|---------|
67+
| Project | GCP project ID | `my-gcp-project-123456` |
68+
| Service Account JSON | Full JSON key file contents | `{"type": "service_account", ...}` |
69+
70+
71+
> **Note**: For authentication, we currently provide support for service account JSON only. More details [here](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#service-account-json).
72+
73+
## Connect Redshift
74+
75+
| Field | Description | Example |
76+
|-------|-------------|---------|
77+
| Host | Cluster endpoint | `my-cluster.abc123xyz.us-west-2.redshift.amazonaws.com` |
78+
| Port | Database port | `5439` (Default) |
79+
| Database | Database name | `analytics_db` |
80+
| Username | Database user | `admin_user` |
81+
| Password | Database password | `my_password` |
82+
83+
84+
> **Note**: We currently support Database (Password-based authentication) only. More details [here](https://docs.getdbt.com/docs/core/connect-data-platform/redshift-setup#authentication-parameters).
85+
86+
## Save Connection
87+
88+
After entering your connection details, click **Save**. Recce Cloud runs a connection test automatically and displays "Connected" on success.
89+
90+
## Verify Success
91+
92+
Navigate to Organization Settings in Recce Cloud. Your data warehouse should appear.
93+
94+
![alt text](../assets/images/2-getting-started/connect-dw.png){: .shadow}
95+
96+
## Troubleshooting
97+
98+
| Issue | Solution |
99+
| --- | --- |
100+
| Connection refused | Whitelist Recce Cloud IP ranges in your network configuration |
101+
| Authentication failed | Verify credentials and regenerate if expired |
102+
| Permission denied on table | Grant SELECT permissions on target schemas |
103+
104+
## Next Steps
105+
106+
- [Add Recce to CI/CD](../7-cicd/setup-ci.md)
107+
- [Run Your First Data Diff](../5-data-diffing/row-count-diff.md)

‎docs/2-getting-started/gitlab-pat-guide.md‎

Lines changed: 0 additions & 84 deletions
This file was deleted.

‎docs/2-getting-started/start-free-with-cloud.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ You can use the Recce Web Agent to help automate your setup. Currently it handle
6060

6161
The agent covers common setups and continues to expand coverage. If your setup isn't supported yet, the agent directs you to the Setup Guide below for manual configuration. Need help? Contact us at support@reccehq.com.
6262

63-
**Coming soon**: The agent will guide you through steps 1–3, including warehouse connection, Git connection, and CI/CD configuration.
63+
The agent will guide you through steps 1–3, including Git connection, data warehouse connection, and CI/CD configuration.
6464

6565
---
6666

@@ -70,20 +70,20 @@ This guide explains each onboarding step in detail.
7070

7171
First, go to [cloud.reccehq.com](https://cloud.reccehq.com) and create your free account.
7272

73-
### 1. Connect Data Warehouse
74-
75-
1. Select your data warehouse (e.g. Snowflake)
76-
2. Provide your read-only warehouse credentials
77-
78-
> **Note**: This guide uses Snowflake. For supported warehouses, see [Connect to Warehouse](../5-data-diffing/connect-to-warehouse.md).
79-
80-
### 2. Connect Git Provider
73+
### 1. Connect Git Provider
8174

8275
1. Click **Connect GitHub**
8376
2. Authorize the Recce app installation
8477
3. Select the repositories you want to connect
8578

86-
> **Note**: This guide uses GitHub. For GitLab setup, see [GitLab Personal Access Token](gitlab-pat-guide.md).
79+
> **Note**: This guide uses GitHub. For supported Git providers, see [Connect to Git](connect-git.md)
80+
81+
### 2. Connect Data Warehouse
82+
83+
1. Select your data warehouse (e.g. Snowflake)
84+
2. Provide your read-only warehouse credentials
85+
86+
> **Note**: This guide uses Snowflake. For supported warehouses, see [Connect to Warehouse](connect-to-warehouse.md).
8787
8888
### 3. Add Recce to CI/CD
8989

0 commit comments

Comments
 (0)