Skip to main content

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:

    NameSUPERBLOCKS_TOKEN
    Secret

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

  4. Save the secret and go back to your repository's main page

  5. Go to the Actions tab and select set up a workflow yourself to start configuring a GitHub Action

  6. 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 }}

    EU region

    If your organization uses Superblocks EU, also set domain to eu.superblocks.com in the Push and Pull steps.

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

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

    Top-level directory is not the root directory

    If the top-level directory of your repository is not the root directory where Superblocks Applications are stored, also set the path to your apps in the Push and Pull steps. For example, if your Superblocks tools are in an existing repository under a ./superblocks directory, set path to './superblocks'.

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

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

  7. 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

Search for Repository

  1. 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.

Configure Repository

  1. 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​

Start using source control on apps and APIs at anytime by adding them to your git repository. Follow the instructions on how to add apps and APIs to your repo.

Once your code is merged to the default branch of your repo and CI runs, Superblocks will start syncing changes 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: