Connect to Git

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: 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 publish the synced changes to production from the Deploy tab in Clark version history

​

Setup

​

Prerequisites

Before connecting, you need:

• A Git repository hosted on one of the supported providers. The repository must be empty
• A Personal Access Token (PAT) with the required permissions for your provider (see 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.

​

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:

​

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:

​

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 publish:

1. Open Clark AI and switch to Version history
2. Open the Deploy tab (your repository’s default branch)
3. Preview the synced version if you want to verify changes
4. Click Publish to make it live for end users

​

Updating your Git token

If your personal access token expires or becomes invalid, open Git Settings from the editor toolbar. You do not need to disconnect the repository.

1. Enter a new PAT in the token field
2. Click Save

Superblocks validates the token and refreshes Git authentication in place. Prefer updating the token this way instead of disconnecting and reconnecting, so the app stays linked to the repository.

​

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. Update the token in Git Settings (see Updating your Git token), and double-check the 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)