# Troubleshooting Guide

This guide helps you resolve common issues when using Git-based Source Control in Nected. If your problem isn’t covered here, pull before pushing, confirm your PAT and branch access, and use GitHub for merge and conflict resolution.

### Connection & authentication

#### Cannot connect to the repository

**Symptoms:** "Failed to connect", "Invalid repository URL", or connection timeout when connecting or syncing.

**What to check:**

1. **Repository URL**
   * Use the correct HTTPS or SSH URL from GitHub (e.g. `https://github.com/org/repo.git` or `git@github.com:org/repo.git`).
   * Ensure the repo exists and you have access in GitHub.
2. **Network & firewall**
   * If you use an On-Premise Agent or corporate network, ensure outbound HTTPS (and SSH if used) to `github.com` is allowed.
   * Proxies or VPNs can block Git; try from a different network to isolate.
3. **Repository immutability**
   * The connected repository cannot be changed after setup. If you need a different repo, you must use a workspace where the correct repo was connected from the start.

[Learn how to connect with GitHub](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/setup/github)

***

#### Personal Access Token (PAT) errors

**Symptoms:** "Authentication failed", "403 Forbidden", "Bad credentials", or "Token expired" when pushing or pulling.

**What to do:**

1. **Token validity**
   * PATs can expire or be revoked. Create a new Fine-grained or Classic PAT in GitHub and add it in Nected via **Git Repository → Add Personal Token** (or update the existing token if your UI allows).
2. **Token permissions**
   * **Fine-grained PAT:** Repository **Contents → Read and Write** for the specific repo.
   * **Classic PAT:** `repo` scope (Read and Write).
   * Ensure the token is for the same GitHub account that has access to the connected repository.
3. **Where to add the token**
   * **Primary admin:** Token is set during **Connect to Git**.
   * **Additional admins:** **Git Repository → Add Personal Token**; they do not reconfigure the repo URL.
4. **Branch protection**
   * If you get 403 only on certain branches, GitHub branch protection may be blocking direct pushes. Use a branch you’re allowed to push to, or use PRs and merge in GitHub, then pull in Nected.

***

#### "Repository is immutable" / Wrong repository connected

**Symptoms:** You need to use a different GitHub repository, but Nected doesn’t allow changing the connected repo.

**Explanation:** The connected repository is fixed per workspace for consistency and auditability.

**Options:**

* Use a workspace that was connected to the correct repository from the start, or
* Connect the correct repository when creating or configuring a new workspace.

***

### Branches

#### I don’t see a branch / Can’t switch to a branch

**Symptoms:** A branch exists in GitHub but doesn’t appear in Nected, or you can’t switch to it.

**What to check:**

1. **GitHub access**
   * Branch visibility in Nected follows your GitHub permissions. You only see branches you have access to in the connected repo.
   * Ask a repo admin to add you as a collaborator or to give your team access to the branch.
2. **Fine-grained PAT**
   * If using a Fine-grained PAT, it must be scoped to the repository that contains the branch. Broader org-level permissions may still be required depending on your GitHub setup.
3. **Refresh**
   * After new branches or permissions are granted in GitHub, try switching branch again or refreshing the Git panel in Nected.

[Learn how branch access works](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/branches)

***

#### Default branch is wrong / Can’t change default branch

**Symptoms:** You want a different default branch (e.g. `main` instead of `master`), but you can’t change it.

**Explanation:** Only the **primary workspace admin** (workspace owner or first admin who connected Git) sets the default branch, and only during initial Git setup.

**What to do:**

* If you’re the primary admin and the repo was just connected, set the correct default branch when prompted.
* If the repo is already connected, the default branch cannot be changed in Nected; use a workspace where the correct default was set at connection time, or reconnect in a new workspace with the desired default.

***

### Push & commit

#### Push conflict: "Workspace differs from GitHub"

**Symptoms:** When pushing, Nected shows that your workspace and the remote branch have diverged (e.g. someone else pushed, or you changed branch/state).

**Your options in Nected:**

| Option                | When to use                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Override and Push** | You intend to replace the remote branch with your current workspace state. Use only when you’re sure you want to overwrite remote changes. |
| **Discard Changes**   | Cancel the push and keep your current local state.                                                                                         |

**If you need to merge instead of overwrite:**

1. Resolve conflicts in **GitHub** (e.g. pull on another clone, fix conflicts, commit, push).
2. In Nected, click **Pull** to bring the updated branch (including the merge) into your workspace.

Nected does not perform merge conflict resolution; GitHub is the source of truth for merging.

[Learn about handling push conflicts](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/commit-and-push#handling-push-conflicts)

***

#### Nothing to push / Changes not appearing in push dialog

**Symptoms:** You edited rules, workflows, or other entities but the push panel shows no changes or an empty list.

**What to check:**

1. **Branch**
   * Confirm you’re on the intended branch. Changes are per-branch; switching branches loads that branch’s state.
2. **Last sync**
   * Push only includes changes since the last push or pull. If you just pulled and made no further edits, there may be nothing to push.
3. **Entity type**
   * Only **Synced Entities** are tracked: Rules, Workflows, Integrations, Datasets, Variables (and related versions). Schedulers, workspace settings, and similar are not synced and won’t appear.
4. **Save**
   * Nected auto-saves, but if you had errors or left the editor before save completed, changes might not be included. Re-open the resource, confirm it’s saved, then try Push again.

***

#### Force push (Override and Push) overwrote remote changes

**Symptoms:** You or a teammate used **Override and Push** and important commits on the remote branch were replaced.

**Prevention:** Prefer normal **Commit and Push**. Use **Override and Push** only when you intentionally want the remote branch to match your current workspace.

**Recovery:** If the overwritten commits were pushed to GitHub recently, you may be able to recover them via GitHub’s commit history or reflog on a clone that still has the old state. Restore the desired state in GitHub (e.g. revert or reset and force push from a clone), then **Pull** in Nected to realign the workspace.

***

### Pull & sync

#### Pull shows "No changes" but GitHub has new commits

**Symptoms:** You merged a PR or pushed from another machine, but Nected’s Pull says there are no changes.

**What to check:**

1. **Branch**
   * Ensure you’re on the same branch in Nected that was updated in GitHub (e.g. `main`).
2. **Caching / refresh**
   * Try closing and reopening the Pull dialog, or refreshing the Git panel, then run Pull again.
3. **GitHub state**
   * In GitHub, confirm the commits are on the branch you’re pulling and that the merge actually completed.

***

#### Pull fails or stops at "Sync Integrations & Credentials"

**Symptoms:** Pull doesn’t complete; it asks you to fix Integrations or credentials.

**Explanation:** Pulled rules and workflows can reference Integrations that don’t exist in your workspace or lack credentials. Credentials are never in Git; they must be configured in Nected.

**What to do:**

1. In the Pull flow, complete **Step 2 — Sync Integrations & Credentials**.
2. For each missing or invalid Integration:
   * Create the Integration in Nected if it’s new, or
   * Map the reference to an existing Integration and ensure credentials (and any config) are set.
3. Retry the pull after all Integration/credential issues are resolved.

[Learn about the pull steps](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/pull-changes)

***

#### Pull conflicts: Merge vs Override vs Archive

**Symptoms:** Nected reports conflicts during pull and offers **Merge & Pull**, **Override & Pull**, or **Archive / Archive Overwrite**.

**What to choose:**

| Option                          | Use when                                                                                                                    |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Merge & Pull**                | You want to keep both remote and local changes where possible. Nected merges automatically where it can.                    |
| **Override & Pull**             | You want the workspace to match the remote branch exactly; local-only changes for conflicting entities will be replaced.    |
| **Archive / Archive Overwrite** | You want to keep the remote version but preserve the local one as archived (exact behavior depends on your Nected version). |

Resolve any remaining conflicts as prompted; then the Git panel should show the branch as in sync.

***

### Sync status (Ahead / Behind / Ahead & Behind)

**Meanings:**

| Status             | Meaning                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Ahead**          | Your workspace has local commits/changes not yet pushed to the remote branch.                                          |
| **Behind**         | The remote branch has commits you don’t have. Pull to update.                                                          |
| **Ahead & Behind** | Workspace and remote have diverged (both have unique commits). Pull first (or resolve in GitHub), then push if needed. |

**If status seems wrong:**

* Pull to get the latest from the branch, then check again.
* Confirm you’re on the correct branch and that no one else force-pushed; that can change history and make local state invalid until you pull (or reset).

***

### Integrations & credentials after sync

#### Integrations missing or broken after pull

**Symptoms:** After pulling, rules or workflows fail with errors about missing Integrations or invalid configuration.

**Explanation:** Git stores Integration **names and metadata** only, not credentials or sensitive configuration. Each environment (e.g. staging, production) must have Integrations created and configured in Nected.

**What to do:**

1. During Pull, complete **Step 2 — Sync Integrations & Credentials** and **Step 3 — Update Missing Configs**.
2. In Nected, open **Integrations** and ensure every Integration referenced by the pulled logic exists and has valid credentials and config for this environment.
3. Re-run or re-publish the affected rules/workflows after fixing Integrations.

***

#### Variables or secrets not syncing

**Symptoms:** Variable names appear after pull but values are empty or prompts ask for secrets.

**Explanation:** By design, variable and secret **values** are not stored in Git; only names (and non-sensitive metadata) are synced. This avoids exposing secrets in the repository.

**What to do:** After pull (or when switching branches), set variable values and secrets in Nected for the current workspace/environment. Use Nected’s Variables and Secrets UI (or your org’s secret management) to fill them in.

***

### Schedulers & Git

**Symptoms:** Schedules don’t appear in Git or don’t run on a non-default branch.

**Explanation:** Schedulers are **not** part of Git sync. They exist only in the Nected workspace and run only on the **default branch** (e.g. `main` or `master`). They are not versioned or merged via Git.

**What to do:** Manage schedulers in Nected. If you need schedule changes to follow a process, document them outside Git (e.g. runbooks or internal docs). When you switch to a non-default branch, expect that schedules are not active for that branch.

***

### On-Premise Agent

**Symptoms:** Git or Source Control options are missing or disabled.

**Check:** Source Control requires **On-Premise Agent v1.0.5 or newer**. Upgrade the agent to at least v1.0.5 and ensure the agent can reach GitHub (and your Git provider if different) for push/pull.

***

### Getting more help

* **Git workflow (PRs, merges, conflict resolution):** Use [GitHub’s documentation](https://docs.github.com) and your team’s branching policy.
* **Nected lifecycle:** See [Overview](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control) and [Commit & Push](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/commit-and-push).
* **Branches and PATs:** See [Branches](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/branches) and [Setup (GitHub)](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/setup/github).

If the issue persists, contact Nected support with your workspace details, branch name, and whether the problem occurs on push, pull, or connection (and any on-screen error message).