---

#title: GitLab integration description: Connect gitlab.com or a self-hosted GitLab: organization connection, personal account binding, issue sync, merge request and commit linking, and private-network proxy access.

#GitLab integration

The GitLab integration provides two connection types:

• GitLab (gitlab.com): the organization connects to gitlab.com with OAuth to link merge requests and commits to tasks, update task states, and post task linkbacks on GitLab.
• Self-hosted GitLab: for your own GitLab instance, connect with a personal access token instead. If the instance is on a private network that the cloud cannot reach, choose an online Computer as a private-network proxy. Issue sync, merge request and commit linking, and linkbacks are supported the same way.

Both live under Integrations. The two connections are independent; bind the one you use.

#Connect gitlab.com

An Organization Owner or Admin can connect the organization on the GitLab page. If the current deployment has no GitLab OAuth credentials configured, the page asks an administrator to set them up first.

After the organization is connected, members can connect their own GitLab account on the same page for notifications and identity matching.

#Connect a self-hosted GitLab

A self-hosted instance does not use OAuth. An administrator completes the organization connection with a personal access token:

1. Open Integrations and go to the GitLab self-hosted page.
2. Enter the GitLab URL, for example https://gitlab.your-company.com (use the root address you open in the browser).
3. Create a personal access token in the GitLab user settings with the api scope, and paste it into the connect dialog. A dedicated bot account is recommended.
4. The token's account needs to be Maintainer or above in the projects to sync, because it creates webhooks, syncs issues, and posts linkback comments.
5. If the instance is on a private network, choose an online Computer that can reach it as the private-network proxy.
6. Choose connect. After it succeeds, the connection shows the token expiry date and the proxy Computer in use.

When the token is invalid, permissions are missing, the address redirects, or the instance cannot be reached, the page says the actual reason; fix the token or address as instructed and try again.

#Using a private-network proxy

When the GitLab instance is on a private network that the cloud cannot reach, choose an online Computer that can open the address as the proxy. After that, Sharkly reaches GitLab through that Computer.

• Only online Computers can be selected; offline ones are not selectable;
• if the proxy Computer is removed, the connection asks you to choose another one;
• if the selected Computer cannot reach the GitLab address, check that the Computer's network can open it.

#Replacing the token

Tokens can be replaced. The connection shows the token expiry date; when the token is about to expire or has expired, the page asks you to replace it so sync and linkbacks do not stop.

#Bind a personal account (self-hosted)

After the organization connects a self-hosted GitLab, members can paste their own personal access token on the same page:

• after binding, comments you write in a task appear on GitLab under your own identity, and assignees sync in both directions;
• your personal token is used only for your comments and assignee sync; it does not change the organization connection;
• if your token is missing or expired, comments are temporarily posted by the organization's account and the page asks you to fill in a token;
• you can bind a personal account to only one GitLab instance at a time; binding here replaces a binding on another instance.

#Issue sync

The GitLab integration includes issue sync: link a GitLab project to a Space and its issues stay in sync with tasks — title, description, state, and comments. Projects on a self-hosted instance can be linked too, and they use the route chosen for the organization connection, including the private-network proxy.

#External accounts and user linking

When issue sync meets a user who does not correspond to an Organization member — for example an issue's author, assignee, or comment author — Sharkly creates an external account for them, as it does for Jira: it records their GitLab identity, takes no seat, and cannot sign in.

External accounts are managed in People → External accounts: filter by platform, search, and link an account to an Organization member. When a member binds their personal GitLab account (on the integration page for gitlab.com, or by token on a self-hosted instance), the matching external account links automatically. After linking, Sharkly backfills the assignee on the historical tasks that account held (hand-edited ones are left alone), and comments and task activity show the linked member with the original GitLab identity noted; unlinking restores the external identity. See External accounts in the Jira integration for the full description.

#Webhook configuration

Merge request and commit linking receives events through a GitLab webhook, which you add to the GitLab project:

• under the project's Settings → Webhooks, add the URL and Secret provided by Sharkly;
• select Push events and Merge request events;
• to link several projects, a group-level webhook is more convenient, but it requires GitLab Premium / Ultimate; on Free, add the same URL and Secret in each project.

The exact URL, Secret, and configuration path are shown in the integration page's setup guide.

#Common questions

#The self-hosted page asks for an administrator connection first

The organization connection for a self-hosted instance must be completed by an administrator with a personal access token before members can bind personal accounts. Ask your administrator to finish the organization connection steps above.

#Connecting says the GitLab address cannot be reached

This appears when the instance is on a private network. Choose a Computer that can open the address as the private-network proxy and connect again; if a proxy Computer is already selected, make sure that Computer's network can open GitLab.

#What permissions does the token need?

A personal access token needs the api scope. An account that syncs issues and posts linkback comments also needs to be Maintainer or above in the relevant projects.

#Does disconnecting delete tasks or code?

No. Disconnecting only stops the association and sync between Sharkly and GitLab. Code, merge requests, and issues on GitLab are not affected.