GitLab setup

The plugin talks to GitLab through the REST API with a Personal Access Token: you do not need git on your computer. Both gitlab.com and self-hosted GitLab servers work.

#Step 1. Create a Personal Access Token

1. In GitLab open User Settings → Access Tokens.
2. Press Add new token, give it a name, for example SXL Studio, and an expiration.
3. Tick the api scope. It is needed to read files, Push and work with branches. A token with only read_api or read_repository allows Pull, but Push and branch creation fail.
4. Press Create personal access token and copy it: it is shown only once.

Tokens from gitlab.com start with glpat-. Older and self-hosted servers may issue tokens without the prefix, which is fine: the plugin notes it in the check report, and GitLab decides whether the token is valid on the first request.

Besides a personal token you can use a project access token or a group access token with the api scope if that is how your company works.

#Step 2. Check your project role

For Push your account needs the Developer role or higher in the project. With Reporter or Guest, Pull works but Push does not. If a branch is protected by project rules, Push into it may be refused even for Developers; work in another branch then.

#Step 3. Find the project path or ID

The Repository field accepts both the project path and its numeric ID:

• path: namespace/project; for a project in a subgroup use the full path group/subgroup/project;
• ID: the number on the project's Settings → General page.

#Step 4. Create the connection in the plugin

1. Press the Sync settings gear in the plugin footer, then New Sync.
2. Fill in the form:

3. Press Test connection. The report should say Connection OK. If the branch or folders are named differently, the Fix button puts the found values in.
4. Press Save, then Use Git to make the connection active.

All form fields and checks are described on the Connecting a repository page.

#Step 5. First synchronization

1. Press Pull in the footer; the plugin loads tokens and data.
2. Change any token and press Push. For GitLab the Push window has a Show format guide link: some projects require Conventional Commits messages, for example feat(ui): add dark mode toggle. If the server rejects the message, the plugin shows Push rejected; fix the text and try again.

Next: Pull, Push and branches.

#Self-hosted GitLab

1. Put the server address into Enterprise URL. The plugin adds the API path itself.
2. Create the token on your server the same way as on gitlab.com.
3. If your server enforces token rotation, update the token in the connection form before it expires: an expired token gives error 401.

#If something does not work

The full list of checks and errors: Connecting a repository. If the cause is unclear, open the Diagnostics tab and run test.

#See also

• Token sources and synchronization
• GitHub setup