> For the complete documentation index, see [llms.txt](https://docs.nected.ai/nected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/setup/gitlab.md). # 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](https://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: 1. Click **Add new token** 2. Give it a name you'll recognize later, like "Nected Sync" 3. Set an expiration date (GitLab requires one — set a reminder to rotate it before it expires) 4. 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_repository` will cover push/pull, but a few sync features that rely on GitLab's API may not work. 5. 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: 1. Open the left sidebar in Nected 2. Scroll down and click **Git Repository** 3. Select **Connect to Git** — this opens the Configure Git dialog
In the dialog: | Field | Description | | ------------------------- | --------------------------------------------------------------------------------------------------- | | 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](http://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](http://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 `api` scope, or at minimum `read_repository` + `write_repository` * Your 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 * [Commit and push updates from Nected into GitLab](/nected-docs/development-lifecycle/git-based-source-control/commit-and-push.md) * [Pull branch updates into your workspace for review](/nected-docs/development-lifecycle/git-based-source-control/pull-changes.md) * [Merge and deploy approved logic to production](/nected-docs/development-lifecycle/git-based-source-control/merge-and-deploy.md)