Connect to GitLab

info

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

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

Prerequisites

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

• A GitLab Cloud account
• Admin access for your GitLab org

Connect to GitLab

1. Create a GitLab Project

Create a GitLab project. This project repository 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. Create Service Account

Superblocks creates commits in GitLab using a Personal Access Token. The author of commits created using the Superblocks UI will appear as the user this access token is associated with. Because of this, we recommends creating a Superblocks service account that commits will be attributed to.

Follow GitLab's instructions to create a user for your Superblocks service account user.

3. Create Access Token

Once you have a Superblocks service account, create an access token.

info

The same access token will be used to commit to all GitLab projects connected to Superblocks. Make sure the Service Accounts has Developer access to projects.

1. Log in to GitLab using your service account's credentials
2. On the left sidebar, select your avatar
3. Select Edit profile
4. On the left sidebar, select Access Tokens
5. Select Add new token
6. Enter a name and expiry date for the token
7. Select the api scope for your token
8. Select Create personal access token
9. Copy the generated personal access token

4. Configure CI

Changes made to outside of Superblocks are synced back to Superblocks using a continuous integration workflow with GitLab Pipelines. To configure this pipeline:

1. Open your GitLab project and navigate to the repository settings.

2. Go to Settings → CI/CD and click on Variables.

3. Add the following variables with the flags shown:

   Key	Value
   SUPERBLOCKS_GITLAB_TOKEN	Your service account's access token.
   SUPERBLOCKS_TOKEN	Superblocks 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 variables and go back to your project's main page.

5. Go to Build → Pipelines and select Try test template to start configuring a GitLab Pipeline.

6. Copy and replace the .gitlab-ci.yml file content with the follow:

   stages:
     - sync
   
   pull:
     stage: sync
     image:
       name: superblocksteam/export-action:v1
       entrypoint: ['']
       pull_policy: always
     before_script:
       # Checkout the branch, because the job runs in detached mode
       - git checkout "$CI_COMMIT_REF_NAME"
   
       # Add authentication for the remote, so we can push
       - git remote remove origin
       - git remote add origin https://oauth2:$SUPERBLOCKS_GITLAB_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git
       - git fetch origin $CI_COMMIT_REF_NAME
       - git branch --set-upstream-to=origin/$CI_COMMIT_REF_NAME
     script: /entrypoint.sh
   
   push:
     stage: sync
     image:
       name: superblocksteam/import-action:v1
       entrypoint: ['']
       pull_policy: always
     before_script:
       # Checkout the branch, because the job runs in detached mode
       - git checkout "$CI_COMMIT_REF_NAME"
     script: /entrypoint.sh

7. Save the file and commit it to your repository.

5. Connect GitLab to Superblocks

Now that your GitLab repository is configured and you have an access token, follow these instructions to connect your GitLab repo to Superblocks.

1. Go to Repositories and click Continue with GitLab

2. Paste the copied access token into the Access token field

3. Find the repository you want to connect to and click Set up

   

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

   

5. Finally, review your repository setup and click Connect

success

Superblocks is now connected to your GitLab project! 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.

Update access token

You can update your GitLab access token from the Repositories page, for example to replace an expiring token.

To update your token, click Manage token and paste in the new token.

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