GitLab Connection
The GitLab connection type enables automations to interact with GitLab projects — reading merge requests and pipeline status, creating issues, and triggering CI/CD pipelines. It supports both GitLab.com and self-hosted GitLab instances.
Connection Details
| Property | Value |
|---|---|
| Type ID | GITLAB |
| Category | Version Control Systems |
| Testable | Yes |
Friendly Example
| What you enter | Example |
|---|---|
| Connection name | GitLab - Deployment Project |
| Used for | Reading merge request status and triggering deployment pipelines |
| Main details to collect | GitLab instance URL and personal access token |
| Best person to provide it | GitLab administrator or project maintainer |
After it is saved, workflow builders select GitLab - Deployment Project in a node instead of entering these details again.
Mandatory Fields
| Field | What It Means | Example |
|---|---|---|
token | GitLab personal access token with the required scopes. Encrypted at rest. | glpat-xxxxxxxxxxxxxxxxxxxx |
gitlabUrl | Full URL of the GitLab instance. Use https://gitlab.com for GitLab.com, or your own instance URL for self-hosted. | https://gitlab.yourcompany.com |
Advanced Fields
| Field | What It Means | Example |
|---|---|---|
apiVersion | GitLab API version to use. Defaults to v4, which is current for all supported GitLab releases. | v4 |
Token Scope Reference
| Scope | What It Allows |
|---|---|
api | Full read/write access to all GitLab API endpoints (groups, projects, pipelines, issues) |
read_repository | Read access to repository contents and files |
write_repository | Push commits and branches (needed if the automation creates or updates files) |
Grant only the scopes the automation actually needs. For read-only automations (monitoring pipelines, reading MRs), read_api or api in read mode is sufficient. Only add write_repository when the workflow pushes changes.
Setup Instructions
-
Sign in to GitLab and click your avatar in the top-right corner, then select Preferences (GitLab.com) or User Settings (self-hosted).
-
In the left sidebar, select Access Tokens, then click Add new token.
-
Fill in the token details:
- Give the token a descriptive name (e.g.,
qinfinite-automation). - Set an expiry date appropriate for your organization's token rotation policy.
- Under Scopes, check api, read_repository, and write_repository as needed by the automation.
- Give the token a descriptive name (e.g.,
-
Click Create personal access token and copy the token immediately. GitLab only shows it once.
-
Create the connection in the Global Configurator. Paste the token into the
Tokenfield and enter the full instance URL (e.g.,https://gitlab.comor your self-hosted URL). Test the connection to confirm access.
For self-hosted GitLab, ensure the platform can reach your instance over HTTPS. If your instance uses a self-signed certificate, you may need to add the CA certificate to the platform's trust store.
Troubleshooting
| Symptom | Likely Cause |
|---|---|
401 Unauthorized | The token is invalid, expired, or was not entered correctly |
403 Forbidden on a specific project | The token user does not have at least Reporter role on that project |
404 Not Found for a project or group | The project path or group path is wrong, or the token lacks api scope |
| Connection test fails for self-hosted GitLab | The gitlabUrl is unreachable, or TLS validation is failing due to a self-signed certificate |