Skip to main content
This guide covers the Git feature in Superblocks: first-time connection to an empty GitHub repo, connecting to an app that is already linked to Git, branch model, workflows, and deployments.

​
Supported provider

  • GitHub only (for now)

​
Before you connect for the first time

Your target repository must be empty.

​
First-time connection steps

Use these steps the first time you connect a Superblocks app to GitHub.
  1. Open Git Settings. Git Settings
  2. Keep the provider set to GitHub.
  3. Enter the remote URL.
  4. Enter a PAT (Personal Access Token) with repo read/write access. See how to generate a PAT in GitHub.
  5. Click Connect. Connect

​
Connect to an existing app

If the app is already connected to Git, you must have access to the repository before you can modify it from Superblocks.
  1. Ask a repo admin to add you as a collaborator in GitHub under Settings → Collaborators and teams: https://github.com/OWNER/REPO/settings/access Add collaborator
  2. When you open an app that is already connected to Git, Superblocks will show a modal asking you to connect your Git credentials. Connect to Git app modal
  3. To modify the app, you must:
    • have access to the repository
    • provide a PAT
    For PAT setup, see To generate a PAT in GitHub or If you cannot scope Repository access to the repo.

​
Branch model

  • Superblocks works on superblocks/live.
  • PRs are typically superblocks/live → main.
  • When superblocks/live is first created and missing on remote, it is based on the remote default branch tip when available.

​
GitHub workflow and secrets

On initial setup, Superblocks may add:
  • .github/workflows/superblocks-sync.yml
This workflow requires two secrets:
SecretDescription
SUPERBLOCKS_TOKENYour Superblocks API key. Find it at Personal settings.
NPM_AUTH_TOKEN (optional)Enables GitHub to automatically sync back to Superblocks when code is merged to main. Add under Settings → Secrets and variables → Actions → New repository secret, or at https://github.com/USERNAME/REPO/settings/secrets/actions.
Adding secrets in GitHub — Settings → Secrets and variables → Actions: New repository secret Secrets and variables – Actions

​
Deployments

When a change is merged to main, CI syncs that commit back to Superblocks. You can then see that exact commit and deploy from the main branch in Version → Deploy. A build is created from that commit, which you can preview and deploy. Deploy

​
Common errors

​
”Cannot set up git for this app…”

The repo is not empty and does not contain a valid .superblocks/superblocks.json for this app id.

​
”Invalid or insufficient permissions for this token”

The PAT cannot access the repo or has missing scopes.

​
”Repository not found”

The remote URL is wrong, the repo does not exist, or the token cannot read it.

​
Appendix

​
To generate a PAT in GitHub

  1. Go to Profile → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token:
    https://github.com/settings/personal-access-tokens
  2. Under Repository access, you can restrict the token to a single repository. Repository access
  3. Ensure the token has:
    • Contents: Read and write
    • Administration: Read-only
    • Workflows: Read and write
    Permissions

​
If you cannot scope Repository access to the repo

If you have access to the repository but GitHub does not let you scope Repository access to that repo when creating a fine-grained token, create a Personal access token (classic) instead.
  1. Go to Profile → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token (classic): https://github.com/settings/tokens Generate new token classic
  2. Give the token these scopes:
    • repo
    • workflow
    Classic PAT permissions