# GitHub

GitHub Sync connects your Nected workspace to a GitHub repository so your team can version-control Rules, Workflows, Integrations, and Datasets directly through Git. Once connected, you can push, pull, review, and merge changes using the same workflows developers already use for application code.

This guide walks you through the requirements and exact steps to configure GitHub Sync for your workspace admin.

### **Important Notes Before You Begin**

{% hint style="warning" %}
A workspace can connect to only one GitHub repository at a time and cannot be changed later.
{% endhint %}

#### **Single-Installation vs Multi-Installation Behavior**

* **Cloud (Single Installation):**\
  A Git repo **cannot** be connected to more than one workspace.\
  To allow additional users to push/pull:
  * Add them to the same Nected workspace
  * Give them appropriate GitHub access (repo RW or branch-specific RW for fine-grained tokens)
* **Self-Hosted (Multi-Installation):**\
  A Git repository **can** be connected to multiple workspaces.

### **Step 1: Create a GitHub Repository**

1. Go to [**https://github.com/new**](https://github.com/new)
2. Create a new repository
3. Copy either of the following:
   * The **HTTPS URL** (e.g., `https://github.com/org/repo.git`)
   * The **SSH URL** (e.g., `git@github.com:org/repo.git`)

Nected accepts **both HTTPS and SSH URLs**.

### **Step 2: Generate a Personal Access Token**

Once the GitHub repo is created, you need to give access to the repository you want to connect to. To do that, you need to permit by creating a [**Fine-grained Personal Access Token or Classic Token**](#user-content-fn-1)[^1]**.** To do so, you need to go to: **GitHub → Settings → Developer Settings**

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FglLfmAzdMmTiV9XDqGNn%2FScreenshot%202025-12-07%20at%202.03.27%E2%80%AFPM.png?alt=media&#x26;token=843d677d-c329-43c6-b0c6-fab87c3f697f" alt=""><figcaption></figcaption></figure>

Now, follow these steps:

#### **Fine-Grained Token (Recommended)**

1. Click on **Personal access tokens → Fine-grained tokens**
2. Click **Generate new token**
3. Fill up all the details and then choose the target repository
4. Under **Repository permissions**, enable:
   * **Contents → Read and Write**
5. Generate and copy the token securely

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FR8bgVc535zEIXGLV9elk%2FScreenshot%202025-12-08%20at%201.13.35%E2%80%AFPM.png?alt=media&#x26;token=ee1c60fb-f495-4a4e-9bb9-daa5b58c4ac1" alt=""><figcaption></figcaption></figure>

#### **Classic Token (Supported)**

Select the scope "repo" as only the **repo (Read & Write)** scope is required.

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FL8Bwu5gtfh2raRkxZ1I4%2FScreenshot%202025-12-08%20at%201.12.18%E2%80%AFPM.png?alt=media&#x26;token=51e50942-5db7-4305-95e2-a4716d7595db" alt=""><figcaption></figcaption></figure>

> **Important:** GitHub only shows tokens once. Store yours securely.

### **Step 3: Configure Git in Nected**

{% hint style="warning" %}
Once a Git repository is connected to a Nected workspace, it **cannot be changed later**.\
Configure the correct repository during setup.
{% endhint %}

Follow these steps to configure the repository in your workspace:

1. In Nected, open the **left sidebar**
2. Scroll to the bottom and click **Git Repository**
3. Select **Connect to Git**\
   A configuration dialog will appear.

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2F8twyIKzTCD4tbmnS5Zhe%2Fimage.png?alt=media&#x26;token=603151d4-198e-43bf-b631-dda5d15518e2" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**Note:** Connecting a Git repository, selecting the default branch, setting the token, and completing initial configuration can only be done by a **Nected workspace admin**.
{% endhint %}

#### **Enter the required fields:**

| Field                     | Description                                     |
| ------------------------- | ----------------------------------------------- |
| **Repository URL**        | Paste the HTTPS URL of your GitHub repo         |
| **Personal Access Token** | Paste your Fine-grained token created in Step 2 |

The dialog displays helpful tooltips for repository URL formats.

4. Click **Configure Git**\
   A loading message appears:\
   \&#xNAN;**“Please wait while we connect to git”**<br>

If successful, Nected will show:

* A green success banner: **“Successfully connected to Github”**
* Sidebar transforms to include:
  * **Branch dropdown**
  * **Push**
  * **Pull**
  * **Settings gear icon**

### **Step 4: Select the Default Branch**

Immediately after connecting, Nected prompts you to choose your default branch.\
Typically `main` or `master`.

1. Select the branch from the **Select default branch** dropdown
2. Click **Save**\
   You will see a success message confirming the default branch selection<br>

The selected default branch represents your **production-ready source of truth**.

### **Troubleshooting GitHub Setup**

#### **SSH Key Misconfiguration**

If using SSH and GitHub does not detect your deploy key, Nected will show:\
\&#xNAN;**“It seems that your SSH key hasn’t been added to your repository…”**

To resolve:

* Add the generated public key to **GitHub → Repo → Deploy Keys**
* Ensure it has write permissions
* Retry configuration

#### **Token Expiration**

If your Fine-grained token expires, you will see:\
\&#xNAN;**“Personal Access Token is expired, Please update.”**<br>

Update it from:\
**Workspace Settings → Git Repo → Personal access token → Update**

#### **Repository Permissions Issues**

If Nected cannot commit or pull:

* Ensure your Fine-grained token includes **Contents: Read & Write**
* Ensure the token is scoped to the correct repository

## **Next Steps**

Once GitHub Sync is successfully configured, you can begin:

* Working on **branches** to isolate changes
* **Committing and pushing** updates from Nected into GitHub
* **Pulling** branch updates into your workspace for review
* **Merging and deploying** approved logic to production

[^1]: Read more about personal access tokens from here: <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>