Connect GitLab

Outcome

Threadory will be able to read issues, merge requests, and selected project code. With write access, it can also create tickets and publish results.

Before you begin

• an administrator or owner role in the Threadory project;
• a GitLab personal access token or project access token for a test project;
• a GitLab project path in group/repository format (or the full project URL);
• scopes sufficient for reading and, for a closed loop / webhook, api.

Connection profile

Item	Minimum or expected behavior
Credential	Prefer a dedicated project access token. A personal access token is supported, but its GitLab user becomes the external actor.
Minimum access	Use read_api for read-only ingestion. Add api only when Threadory must create issues, post comments, or install a project webhook.
Identity	This is a shared service credential, not per-user OAuth. GitLab records writes as the token owner; Threadory audit data records the requesting user.
Direction and entities	Inbound: issues, merge requests, and selected code_file entities. Outbound issue/MR actions require api.
Delivery mode	Incremental polling runs every 60 minutes. A project webhook provides low-latency MR, issue, note, and push events; polling remains the fallback.

Steps

1. Open Connectors and select Connect on GitLab (or a recommended card).
2. Follow the interactive guide in the drawer: where to go in GitLab, which scopes (read_api minimum, api for write-back and webhooks), and how to read the project path from the URL. Open GitLab / Open personal access tokens deep-links open the right pages (for self-managed they follow the GitLab base URL field in Paste credentials).
3. Set GitLab base URL if needed, paste the token and project path or full project URL, then select Connect GitLab.
4. On the webhook step, select Install webhook (Threadory mints the webhook secret) or Use polling for now. Without a webhook, MR/issue reaction is slower (polling).
5. Return to the connection card and select Sync now.

Verify the result

• the installation appears on Connectors;
• the webhook is marked as installed, or polling fallback is shown explicitly;
• synchronization completes successfully in Activity;
• issues and merge requests appear in Knowledge.

Common problems

Symptom	Cause	What to do
Access verification fails	The URL, token, or project path is incorrect	Verify the values against the test project; never send the token
Reading works but issue creation does not	The token has no write permission	Grant the minimum write scope and reconnect safely
The webhook is not installed	Token lacks api / hooks rights, or project path is wrong	Grant api, reinstall webhook from the card menu, or keep polling
Events arrive late	The webhook is missing or unhealthy	Check webhook health on the GitLab connection card

Safe disconnection

Disconnecting stops future synchronization and write-back. It does not reverse issues or comments already created in GitLab, and it does not automatically delete imported Threadory entities.

1. Pause workflows and approvals that can write to GitLab.
2. Export required project data.
3. Record the project webhook URL, then disconnect the connector in Threadory.
4. In GitLab, remove the recorded webhook if it remains.
5. Revoke the token if it was dedicated to this connector. Do not revoke a shared personal token until its other consumers are identified.
6. Apply the documented retention process to imported data that must be removed.

Verify that the connector card is gone, the project webhook is absent, and no new sync or write activity appears. To recover, reconnect with a new least-privilege token and run Sync now; already published GitLab writes must be corrected in GitLab and cannot be rolled back by reconnecting.

Next step

Connect tl;dv or Zoom as a meeting source, or complete your first closed loop.