> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect to Git
> Connect your Superblocks applications to a Git repository for version-controlled, PR-based development workflows.
Superblocks Git lets you connect each application to its own Git repository. Once connected, you get a full PR-based development workflow: edit in Superblocks, commit and push to your repo, open a pull request, and deploy once merged.
## Supported providers
Superblocks works with any of the following Git hosting providers:
| Provider | Remote URL format |
| ---------------------- | --------------------------------------------- |
| **GitHub** | `https://github.com/org/repo.git` |
| **GitLab Cloud** | `https://gitlab.com/group/repo.git` |
| **GitLab Self-Hosted** | `https://gitlab.example.com/group/repo.git` |
| **Bitbucket** | `https://bitbucket.org/workspace/repo.git` |
| **Azure DevOps** | `https://dev.azure.com/org/project/_git/repo` |
Both HTTPS and SSH remote URL formats are supported.
## Repository model
Each Superblocks application is connected to **one Git repository**. The repository stores the application's definition files and a CI/CD pipeline configuration that keeps Superblocks in sync.
When you first connect an app, Superblocks initializes the repository with your application's files and creates a CI pipeline file appropriate for your provider.
## Branching model
Superblocks uses a two-branch workflow:
* **`superblocks/live`** — the working branch where all edits happen in the Superblocks editor
* **`main`** (or your repository's default branch) — the production branch that represents what is deployed
### Development workflow
1. You edit on the **`superblocks/live`** branch in the Superblocks editor
2. When you want to sync your changes to Git, you make a commit
3. Once you want to promote your changes to production, you create a pull request in your Git repository
4. You go through your review process in Git and merge your PR when ready
5. These changes sync back to Superblocks via your CI/CD pipeline
6. You deploy the changes to production from the Versions panel
When `superblocks/live` is created for the first time and does not yet exist on the remote, it is based on the tip of your repository's default branch.
## Setup
### Prerequisites
Before connecting, you need:
* A Git repository hosted on one of the [supported providers](#supported-providers). **The repository must be empty**
* A **Personal Access Token (PAT)** with the required permissions for your provider (see [token permissions](#token-permissions) below)
### Connect an application to Git
1. Open your application in the Superblocks editor
2. Open **Git Settings** from the editor toolbar
3. Select your **Git provider** from the dropdown
4. Enter the **remote URL** of your repository
5. Enter your **Personal Access Token**
6. Click **Connect**
Superblocks validates your credentials, initializes the repository, and switches the editor to the `superblocks/live` branch.
After connecting to Git, existing checkpoints created before the connection will no longer be restorable. Make sure you are satisfied with the current state of your application before proceeding.
### Set up the CI/CD pipeline
After connecting, Superblocks automatically adds a CI/CD configuration file to your repository. This pipeline syncs changes from `main` back to Superblocks whenever a merge occurs.
To complete the setup, add your **Superblocks token** as a CI/CD secret:
1. Copy your Superblocks API token from **Personal Settings → API Key** (the Git setup screen also displays it for you)
2. In your Git provider, navigate to the secrets or variables settings for your repository and add a secret named `SUPERBLOCKS_TOKEN` with the token value
The CI/CD file and secrets location depend on your provider:
**CI file:** `.github/workflows/superblocks-sync.yml`
**Add the secret:** Repository **Settings → Secrets and variables → Actions → New repository secret**
Add `SUPERBLOCKS_TOKEN` with your Superblocks API key.
Optionally, add `NPM_AUTH_TOKEN` if the Superblocks CLI package is hosted in a private GitHub Packages registry.
**CI file:** `.gitlab-ci.yml`
**Add the variable:** Repository **Settings → CI/CD → Variables**
Add `SUPERBLOCKS_TOKEN` with your Superblocks API key. Mark it as **Protected** and **Masked**.
**CI file:** `bitbucket-pipelines.yml`
**Add the variable:** Repository **Settings → Repository variables**
Add `SUPERBLOCKS_TOKEN` with your Superblocks API key. Check **Secured** to mask the value in logs.
**CI file:** `.azure-pipelines/superblocks-sync.yml`
**Add the variable:**
1. First, create a pipeline from the `.azure-pipelines/superblocks-sync.yml` YAML file
2. Then open the pipeline editor and add a variable named `SUPERBLOCKS_TOKEN` with your Superblocks API key. Mark it as **secret**
### Connect additional users
If another team member needs to work on an app that is already connected to Git, they need:
1. **Repository access** — ask a repo admin to add them as a collaborator
2. **A valid PAT** — when they open the app for the first time, Superblocks prompts them to enter their own personal access token
Each user authenticates independently with their own PAT, so commits are attributed to the correct author.
## Token permissions
The required PAT permissions vary by provider:
Use a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) scoped to your repository:
| Permission | Access level |
| ------------------ | -------------- |
| **Administration** | Read-only |
| **Contents** | Read and write |
| **Metadata** | Read-only |
| **Workflows** | Read and write |
If GitHub does not let you scope a fine-grained token to the repository (this can happen for some organization settings), create a [classic personal access token](https://github.com/settings/tokens) with the **repo** and **workflow** scopes instead.
Use a [personal access token](https://gitlab.com/-/user_settings/personal_access_tokens) or a project access token:
| Setting | Value |
| ------------------------------------- | ---------- |
| **Scope** | `api` |
| **Role** (project access tokens only) | Maintainer |
For self-hosted GitLab, create the token from your instance's token settings page.
Use a [repository access token](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/) created in your repository's settings:
| Permission | Access level |
| ----------------- | -------------- |
| **Repositories** | Read and Write |
| **Pull requests** | Read and Write |
| **Pipelines** | Read |
Use a [personal access token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) scoped to the organization that owns the repository:
| Permission | Access level |
| -------------------- | ------------ |
| **Code** | Read & Write |
| **Project and Team** | Read |
## Using Clark for Git
You can use **Clark**, the Superblocks AI assistant, to perform Git operations directly from the editor. If the app is not yet connected to Git, asking Clark to run a Git operation triggers the setup flow automatically.
Once connected, you can ask Clark things like:
* *"What's the current git status?"*
* *"Show me the recent commits"*
* *"Commit my changes with the message 'fix: update button styles'"*
* *"Pull the latest changes from remote"*
## Deploying changes
When a change is merged to `main`, the CI/CD pipeline syncs that commit back to Superblocks. To deploy:
1. Open the **Versions** panel in the editor
2. Find the synced commit on the `main` branch
3. Preview the commit to verify your changes
4. Click **Deploy** to make it live for end users
## Disconnecting from Git
If you need to disconnect an application from Git:
1. Open **Git Settings** from the editor toolbar
2. Click **Disconnect**
3. Type the repository name to confirm
Disconnecting removes the link between the app and the repository. The repository itself is not deleted or modified.
## Troubleshooting
### "Invalid or insufficient permissions for this token"
The PAT cannot access the repository or is missing required scopes. Double-check the [token permissions](#token-permissions) for your provider.
### "Repository not found"
The remote URL is incorrect, the repository does not exist, or the token does not have access to it.
### CI/CD pipeline not syncing
Verify that:
* The `SUPERBLOCKS_TOKEN` secret is set correctly in your provider's CI/CD settings
* The CI/CD configuration file exists in your repository and has not been modified or deleted
* The pipeline is triggered on pushes to `main` (or your default branch)