GitHub Integration

GitHub is the backbone of Zingle's Git-native workflow. Every model, semantic definition, and compute optimization ships as a pull request to your GitHub repository.

---

What you need

Requirement	Details
GitHub repository	Public or private repo where your dbt models live
Personal access token	Token with repo scope for creating branches and PRs
Default branch	Zingle needs to know the main branch (e.g., main, master)

---

Connecting a repository

1. Navigate to Connections

   Open Connections from the sidebar. The Connected Repositories section shows all linked repos.

2. Add a repository

   Click Connect Repository and provide:

   • A GitHub URL (e.g., https://github.com/your-org/your-repo), or
   • An org/repo name (e.g., your-org/your-repo)

   Zingle validates that the repository exists and is accessible with your token.

3. Wait for the initial sync

   After connecting, Zingle automatically scans the repository:

   • Clones the repo
   • Indexes models, tests, macros, and semantic-layer files
   • Builds a lineage graph used by the modeling workspace

   Sync status appears as: Pending → In Progress → Success (or Error)

---

Repository management

Once connected, each repository card shows:

Field	Description
Repo name	org/repo identifier
Sync status	Last sync result and timestamp
Models	Count of detected dbt models
Tests	Count of detected test files
Macros	Count of detected macros
Packages	Count of detected dbt packages

Available actions

• Sync — re-scan the repository for changes (useful after direct pushes to GitHub)
• Disconnect — remove the repository from Zingle

---

How PRs work

When you create a PR from any Zingle surface (Data Pipelines, Semantic Layer, Compute Optimization, or Data Model Optimization), the backend:

1. Validates the repository belongs to the current workspace
2. Retrieves the stored GitHub access token
3. Creates a new branch (e.g., zingle/model-{name} or zingle/compute-optimization-{id})
4. Commits all relevant files (SQL, YAML, tests)
5. Opens a pull request against the default branch

The PR includes a descriptive title and body generated by Zingle with context about the changes.

---

GitHub OAuth

Zingle supports GitHub OAuth for seamless authentication:

1. Click Connect with GitHub during setup
2. Authorize the Zingle application
3. The OAuth callback stores your access token securely

The token is used for repository operations (cloning, branching, PR creation) and is never exposed in plaintext.

---

Troubleshooting

ACCESS_TOKEN_REQUIRED

The repository connection doesn't have a valid access token. Go to Connections → Repositories, disconnect, and reconnect with a valid token.

REPO_NOT_FOUND

The repository ID doesn't belong to the current workspace, or the repo was deleted on GitHub. Verify the repo is still accessible and reconnect if needed.

Sync stays in "In Progress"

If a sync doesn't complete within a few minutes:

• Check that the repository is accessible with your token
• Ensure the default branch exists
• Try clicking Sync again to trigger a fresh scan