GitLab
GitLab Sync connects your Nected workspace to a GitLab repository so your team can version-control Rules, Workflows, Integrations, and Datasets through Git. Once it's connected, you push, pull, review, and merge changes the same way your team already does for application code — just from inside Nected.
This guide covers the requirements and the exact steps to set up GitLab Sync for your workspace.
Important Notes Before You Begin
A workspace can connect to only one Git repository at a time, and this cannot be changed later.
Single-Installation vs Multi-Installation Behavior
Cloud (Single Installation): A Git repo cannot be connected to more than one workspace. To let additional users push/pull:
Add them to the same Nected workspace
Give them the right GitLab access on the repo (Developer role or above is generally needed for push access)
Self-Hosted (Multi-Installation): A Git repository can be connected to multiple workspaces.
Step 1: Create a GitLab Repository
Go to gitlab.com/projects/new and create a new project (or use an existing one).
Copy the HTTPS URL of the repo — something like https://gitlab.com/group/project.git. Nected's GitLab integration works over HTTPS with a personal access token, so this is the only URL format you'll need here.
Step 2: Generate a Personal Access Token
Once your GitLab repo is ready, you need a token so Nected can read and write to it. GitLab calls this a Personal Access Token, and you generate it from your own account settings — not from inside the project.
Go to GitLab → click your profile picture (top right) → Edit profile → Access Tokens. Or just jump straight to it: https://gitlab.com/-/user_settings/personal_access_tokens.
From there:
Click Add new token
Give it a name you'll recognize later, like "Nected Sync"
Set an expiration date (GitLab requires one — set a reminder to rotate it before it expires)
Under scopes, select api. This gives Nected full read/write access to the repository content, branches, and commits it needs to push and pull changes. If you'd rather scope it down to just Git operations,
read_repository+write_repositorywill cover push/pull, but a few sync features that rely on GitLab's API may not work.Click Create personal access token
GitLab shows the token only once. Copy it somewhere safe before you navigate away — there's no way to retrieve it again later.
Step 3: Configure Git in Nected
Once a Git repository is connected to a Nected workspace, it can't be changed later — double check the repo before you configure it.
Only a Nected workspace admin can connect a Git repository, select the default branch, and set the token.
To get to the setup screen:
Open the left sidebar in Nected
Scroll down and click Git Repository
Select Connect to Git — this opens the Configure Git dialog
In the dialog:
Git Provider
Select GitLab from the dropdown (GitHub is the other option)
Repository URL
Paste the HTTPS URL of your GitLab repo, in the format https://gitlab.com/username/repository.git
Self Hosted
Toggle on only if you're running a self-managed GitLab instance (see below)
Add personal access token
Paste the token from Step 2
Click Next after entering the repository URL, then paste your personal access token and click Configure Git.
If the token or URL is wrong, you'll see an error right in the dialog — something like "You do not have access to the remote repository. Please check your permissions." Double-check the repo URL and that the token has the api (or read_repository/write_repository) scope.
If it connects successfully, Nected shows a success banner and the sidebar changes — you'll now see a branch dropdown, Push, Pull, and a settings gear icon where "Connect to Git" used to be.
Connecting a Self-Hosted GitLab Instance
If your team runs its own GitLab instance instead of gitlab.com, toggle Self Hosted on before entering your token. Two extra fields show up:
REST Endpoint — the REST API base URL of your self-hosted instance
GraphQL Endpoint — the GraphQL API URL of your self-hosted instance
Fill both in along with the repository URL and personal access token, then click Configure Git. Everything else about the flow — the token scopes, the default branch step below, troubleshooting — works the same as it does for gitlab.com.
Step 4: Select the Default Branch
Right after the connection succeeds, Nected asks you to pick a default branch — usually main or master.
Select it from the Select default branch dropdown and click Save. You'll get a confirmation once it's set.
This branch is treated as your production source of truth going forward, so pick the one your team actually deploys from.
Troubleshooting GitLab Setup
"You do not have access to the remote repository"
This shows up when the token is invalid, expired, or doesn't have enough scope. Check that:
The token was copied correctly (no extra spaces, nothing truncated)
It has
apiscope, or at minimumread_repository+write_repositoryYour GitLab account actually has Developer access or higher on the repo — a token can't grant access you don't already have
Repository URL rejected
Nected expects the HTTPS format exactly: https://gitlab.com/username/repository.git. SSH URLs aren't supported for GitLab right now, so if you're used to connecting via SSH on GitHub, this is one place the two providers differ.
Self-hosted connection fails
Usually this means the REST or GraphQL endpoint is wrong, or Nected can't reach your instance over the network. Confirm both endpoints resolve from a browser first, and that there's no firewall blocking outbound access from Nected.
Token expired
GitLab access tokens always have an expiry date — there's no option to create one that lasts forever. When yours expires, generate a new one from the same Access Tokens page and update it in Nected from Workspace Settings → Git Repo → Personal access token → Update.
Next Steps
Once GitLab Sync is connected, you can:
Work on branches to isolate changes
Last updated