> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up GitLab

> Connect a GitLab project to Upsun Dispatch so Upsun Dispatch can review merge requests.

Connect GitLab to run the built-in [Code review](/dispatch/docs/workflows/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.

<Note>
  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](/dispatch/docs/models).
</Note>

## 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.

<Steps>
  <Step title="Open GitLab integration settings">
    In Upsun Dispatch, open your organization settings, go to **Integrations**, and choose **GitLab**.
  </Step>

  <Step title="Start the project connection">
    Choose to connect a project.
  </Step>

  <Step title="Enter the GitLab project details">
    Enter the same GitLab instance URL and the project path, such as `group/project`.
  </Step>

  <Step title="Provide the one-time token">
    Enter a one-time token with permission to manage webhooks for that project.
  </Step>

  <Step title="Choose service account access if prompted">
    If prompted, choose whether Upsun Dispatch should invite or grant the service account access to the project.
  </Step>

  <Step title="Connect the project">
    Complete the connection from the GitLab integration settings.
  </Step>
</Steps>

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](/dispatch/docs/workflows/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:

```text theme={null}
@<configured-bot-username> review
@<configured-bot-username> full review
@<configured-bot-username> cancel
```

`review` requests a review. `full review` forces a complete re-review. `cancel` requests cancellation of the current review. For behavior details, see [Code review](/dispatch/docs/workflows/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](/dispatch/docs/workflows) 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.

<Warning>
  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.
</Warning>

## 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.