Skip to main content
Connect GitLab to run the built-in Code review workflow on merge requests. After setup, Upsun Dispatch can receive GitLab merge request events, clone the connected project with read-only access, and publish review progress and results back to GitLab.
Code review requires an organization-level AI model key. Upsun Dispatch supports model keys for OpenAI and Anthropic. If you have not added one yet, store it before running your first review. See AI models.

​
What you need

To connect a GitLab project, prepare:
  • A GitLab HTTPS instance URL, such as https://gitlab.com. Use only the origin, with no path, query string, username, or password.
  • A shared GitLab service account for your Upsun Dispatch organization.
  • An api-scope personal access token (PAT) for the service account.
  • A read-only PAT for the same service account.
  • A one-time token that can administer webhooks for the project you want to connect.
  • The GitLab project path, for example group/project.
Upsun Dispatch verifies the service account credentials, stores them securely, and never shows the token values again.

​
Register a GitLab service account

A GitLab service account gives Upsun Dispatch an organization-scoped identity for GitLab access.
  1. In Upsun Dispatch, open your organization settings and go to Integrations.
  2. Choose GitLab.
  3. Add the GitLab instance URL.
  4. Enter the service account api-scope PAT.
  5. Enter the service account read-only PAT.
  6. Save the service account.
Upsun Dispatch validates both tokens before storing them. If you later remove the stored GitLab credential, Upsun Dispatch refuses the removal while connected projects still depend on it, including paused connections.

​
Connect a GitLab project

After the service account is registered, connect each project you want Upsun Dispatch to review.
1

Open GitLab integration settings

In Upsun Dispatch, open your organization settings, go to Integrations, and choose GitLab.
2

Start the project connection

Choose to connect a project.
3

Enter the GitLab project details

Enter the same GitLab instance URL and the project path, such as group/project.
4

Provide the one-time token

Enter a one-time token with permission to manage webhooks for that project.
5

Choose service account access if prompted

If prompted, choose whether Upsun Dispatch should invite or grant the service account access to the project.
6

Connect the project

Complete the connection from the GitLab integration settings.
During connection, Upsun Dispatch:
  • Scans the available GitLab projects so you can pick the project path to connect.
  • Verifies that the service account can access the project.
  • Registers a project webhook so GitLab can send merge request and merge request note events.
  • Creates a per-project read-only deploy/clone token for workflow runs.
  • Records the connection and refreshes repository data so the project appears in Upsun Dispatch.
The one-time token and any project scan results are discarded after the request. Upsun Dispatch uses the per-project deploy token for current GitLab run cloning.

​
Control write access for a GitLab project

GitLab project connections use read-only cloning by default. Keep write access off for projects that only need Code review. Turn on write access only for projects where a Upsun Dispatch workflow needs to write changes back to GitLab. To change write access for a connected project:
  1. In Upsun Dispatch, open your organization settings and go to Integrations.
  2. Choose GitLab.
  3. Open the connected project you want to update.
  4. Use the project’s write access control to enable or disable write access.
Write access is managed per project. Changing it for one connected GitLab project does not change write access for other connected projects.

​
Review GitLab merge requests

When the project is connected, Upsun Dispatch can run Code review on GitLab merge requests. If the workflow trigger mode is automatic, opening or updating a merge request can start a review. Upsun Dispatch posts progress as a GitLab merge request note and commit status while the review runs, then publishes review findings back to GitLab. For review behavior details, including automatic reviews, manual requests, summaries, and review outputs, see Code review.

​
Start or cancel a review manually

GitLab commands must be whole-message commands addressed to the bot username configured for your GitLab connection. Ordinary notes, bot notes, system notes, and self-triggered notes are ignored. Use comments like these on a merge request:
review requests a review. full review forces a complete re-review. cancel requests cancellation of the current review. For behavior details, see Code review.

​
Review merge requests from fork authors

GitLab merge request review includes an organization or repository workflow setting that can allow fork authors. Use this setting when you want Upsun Dispatch to review merge requests from fork-based contributors. Manage workflow settings and repository overrides in the Upsun Dispatch console. See Workflows in Upsun Dispatch for available workflow settings.

​
Recheck, pause, resume, or clean up a connection

Use the GitLab integration controls in Upsun Dispatch to manage an existing project connection:
  • Recheck verifies the connection again. Recheck is not available while the connection is paused. If the service account token has expired or been revoked, recheck reports that the credential is not OK without changing the project’s connection status.
  • Pause stops the connection from being active without deleting its record.
  • Resume makes a paused connection active again.
  • Disconnect removes the Upsun Dispatch connection record.
  • Webhook cleanup removes the GitLab webhook when you provide a one-time token with the required project permission.
  • Deploy token cleanup removes the per-project deploy token when you provide a one-time token with the required project permission.
Disconnecting a GitLab project from Upsun Dispatch does not automatically remove the GitLab webhook or deploy token. Use the cleanup actions when you want Upsun Dispatch to remove those GitLab resources.

​
Troubleshooting

​
The project does not appear in Upsun Dispatch

Confirm that the project connection completed successfully and that the project path matches the GitLab project. Upsun Dispatch refreshes repository data after a successful connection.

​
Recheck says the credential is not OK

The stored service account token may have expired or been revoked in GitLab. Register a valid service account credential before trying to use dependent project connections.

​
Manual comments do not start a review

Check that the comment is a whole-message command addressed to the configured GitLab bot username, such as @<configured-bot-username> review. Comments that include unrelated text are treated as ordinary comments and ignored.
Last modified on September 16, 2026