Connect to GitHub

info

If running the On-Premise Agent, upgrade your agent to v1.0.5+ to access Source Control.

Connect GitHub repositories to Superblocks commits sync automatically between GitHub and Superblocks. This guide walks through how to configure GitHub to sync changes to your repositories.

Prerequisites

To connect your GitHub repository to Superblocks you’ll need:

• A GitHub Cloud account
• Permission to install GitHub Apps to your organization

Connect to GitHub

1. Create a GitHub Repository

Create a GitHub repository. This repo can store one or more Superblocks Applications, Workflows, or Scheduled Jobs for source control.

Once you have a repo, Add Superblocks Applications to your repo or continue setup and do this later.

2. Configure CI

Changes made to outside of Superblocks are synced back to Superblocks using a continuous integration workflow with GitHub Actions. To configure your GitHub Actions:

1. Open your GitHub repository and navigate to the repository settings
2. In the Security section, click Secrets and variables → Actions
3. Click New repository secret and enter the following information:

Name	SUPERBLOCKS_TOKEN
Secret	Access token for an admin in your organization. You can find your access token at https://app.superblocks.com/personal-settings#apiKey

1. Save the secret and go back to your repository's main page
2. Go to the Actions tab and select set up a workflow yourself to start configuring a GitHub Action
3. Copy and paste the following code into the workflow file:

name: Sync changes to Superblocks
on: [push]

jobs:
  superblocks-sync:
    runs-on: ubuntu-latest
    name: Sync to Superblocks
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Push
        uses: superblocksteam/import-action@v1
        id: push
        with:
          token: ${{ secrets.SUPERBLOCKS_TOKEN }}

      - name: Pull
        uses: superblocksteam/export-action@v1
        id: pull
        with:
          token: ${{ secrets.SUPERBLOCKS_TOKEN }}

4. Name your workflow file and commit it to your repository

3. Connect GitHub to Superblocks

Now that your GitHub repository is configured, follow these instructions to connect your GitHub repo to Superblocks.

1. Go to Repositories and click Continue with GitHub
2. Follow the prompts to Sign-in to GitHub and authorize Superblocks
3. Follow the on-screen instructions to Install the Superblocks App to your GitHub organization
4. Find the repository you want to connect and click Set up

5. Optionally, configure repository settings

   • Use Branch to specify the release branch for your repository. Only commits on this branch can be deployed in Superblocks and will serve as the base branch for all new branches.

   • In some cases the top-level directory of your repository may not be the root directory where Superblocks Applications are stored. For example, if you put your Superblocks tools in an existing internal tools repository and have Superblocks code in a ./superblocks directory.

     In this case, set the Directory field to the directory where Superblocks code is located.

6. Finally, review your repository setup and click Connect

tip

Superblocks is now connected to your GitHub repository! Any Application on the default branch of your repo will start syncing immediately.

Add applications to repo

New Applications can be added to your repository at any time to check them into source control. Just follow the Initialize Applications to your repository instructions in the repository setup guide.

Once your Application's configuration files have been merged to the default branch of your repository, refetch the Superblocks configuration from the Repository page. Applications added will start syncing immediately.

What's next?

With your repo configured and connected to Superblocks, you're all set to start building with Source Control in Superblocks. Learn more about how to:

• Setup Branches
• Commit and Push
• Merge and Deploy