Skip to main content

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.

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:
ProviderRemote URL format
GitHubhttps://github.com/org/repo.git
GitLab Cloudhttps://gitlab.com/group/repo.git
GitLab Self-Hostedhttps://gitlab.example.com/group/repo.git
Bitbuckethttps://bitbucket.org/workspace/repo.git
Azure DevOpshttps://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
Branching diagram showing edits on superblocks/live merging into main for deployment

​
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. 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.
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.ymlAdd the secret: Repository Settings → Secrets and variables → Actions → New repository secretAdd 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.

​
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 scoped to your repository:
PermissionAccess level
AdministrationRead-only
ContentsRead and write
MetadataRead-only
WorkflowsRead 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 with the repo and workflow scopes instead.

​
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 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)