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

# GitLab

> Connect GitLab with a personal access token for automations.

## Connection setup

Connect GitLab with a personal access token to use GitLab actions in Flow automations. The token's scopes, the GitLab tier, and the account's GitLab permissions determine which actions can succeed.

This Preview connection supports GitLab.com, self-managed GitLab, and GitLab Dedicated instances. Flow verifies the connection with a read-only projects request before saving it.

## Prerequisites

* A GitLab instance reachable over HTTPS.
* A Flow admin who can manage integrations.
* A GitLab account with access to the projects that automations need.
* A GitLab personal access token with the `api` scope.
* The `admin_mode` scope if the selected GitLab instance requires Admin Mode for administrator API requests.

Use a token created for Flow. Do not reuse a personal token that also grants access for unrelated scripts or tools.

## Provider setup

Create the token in GitLab before you connect Flow.

<Steps>
  <Step title="Open GitLab access tokens.">
    In GitLab, open your user preferences and select **Access tokens**.
  </Step>

  <Step title="Create a personal access token.">
    Give the token a name that identifies Flow and the automation environment.
  </Step>

  <Step title="Set an expiration date.">
    Choose a date that matches your organization's credential rotation policy.
  </Step>

  <Step title="Select the required scopes.">
    Add `api`. If the selected GitLab instance requires Admin Mode for administrator API requests, also add `admin_mode`.
  </Step>

  <Step title="Create and copy the token.">
    GitLab shows the token once. Copy it and enter it only in the Flow connection form.
  </Step>
</Steps>

The `api` scope gives broad REST API access through the token owner's GitLab permissions. Restrict the GitLab administrator account, project memberships, and instance settings to the automation work that Flow must perform.

## Verify provider access

Before you connect Flow, confirm that the token can list projects on the selected GitLab instance. Replace the example host with your GitLab instance origin.

```bash theme={null}
curl --request GET \
  --header "PRIVATE-TOKEN: <personal-access-token>" \
  "https://gitlab.example.com/api/v4/projects?per_page=1"
```

A `200` response with a JSON array means GitLab accepts the token and exposes the selected instance to the account. An empty array is valid. A `401`, `403`, or `404` response means Flow cannot verify the connection.

## Connect in Flow

<Steps>
  <Step title="Open Integrations.">
    Search for **GitLab**. This connection is available to organizations with Preview access.
  </Step>

  <Step title="Select Connect.">
    Name the connection and choose which teams can access it.
  </Step>

  <Step title="Enter the GitLab instance URL.">
    Use the HTTPS origin for the instance, for example `https://gitlab.example.com`. Do not include `/api/v4`, a path, query, or fragment.
  </Step>

  <Step title="Enter the personal access token.">
    Paste the token you created in GitLab.
  </Step>

  <Step title="Complete verification.">
    Flow checks that the token can list projects on the selected instance.
  </Step>

  <Step title="Enable Automations for the intended team.">
    Open the connection and enable **Automations** for each team that needs it. Sharing a connection does not enable automations.
  </Step>

  <Step title="Select the permitted actions.">
    Review action access and approval requirements before using the connection in an automation.
  </Step>
</Steps>

## Capabilities

Use the connection to manage GitLab issues, projects, merge requests, pipelines, users, group members, project members, vulnerabilities, and instance audit events. Each action still depends on the token owner's GitLab permissions and the selected instance's tier.

### GitLab tier requirements

Most GitLab actions work on Free, Premium, and Ultimate tiers when the token owner has the required GitLab role. These actions require an upgraded tier:

| Actions | GitLab tier |
| - | - |
| List all instance audit events | Premium or Ultimate on self-managed GitLab or GitLab Dedicated |
| List, retrieve, confirm, dismiss, or resolve vulnerabilities | Ultimate |

## Automation connector reference

Use the generated [GitLab action reference](/automations/connectors/gitlab) for supported actions, inputs, and risk tiers.

## Sync and behavior

This connection runs actions when an automation requests them. It does not sync Knowledge or Assets, or receive GitLab webhooks.

Flow verifies the token with a read-only project list request during setup. That check proves only that the selected token can reach the selected GitLab instance. GitLab can still reject later actions when the token lacks a project, group, user, admin, or tier permission.

To rotate the token, create a replacement token for the same GitLab instance and reconnect in Flow. Test the actions your automations need with the replacement before you revoke the old token.

## Troubleshooting

| Symptom | What to check |
| - | - |
| GitLab rejects the token | Confirm that the token is valid, active, and has the `api` scope. |
| Flow cannot verify the connection | Confirm that the instance URL is correct and the token can list projects. An empty project list is valid. |
| The instance URL is rejected | Enter the HTTPS origin only, such as `https://gitlab.example.com`. Remove paths, ports, query strings, fragments, and embedded credentials. |
| A project or group action fails | Check the token owner's membership and role on that project or group. |
| An admin action fails | Check the token owner's administrator status and whether Admin Mode applies on the instance. |
| An audit event action fails | Check that the instance is self-managed GitLab or GitLab Dedicated on Premium or Ultimate and that the token owner is a GitLab administrator. |
| A vulnerability action fails | Check that the GitLab project has Ultimate features available and that the token owner can use the project security dashboard. |
| The connection exists but an automation cannot use it | Enable Automations for the intended team and select the permitted actions. |

## Related

* [GitLab personal access tokens](https://docs.gitlab.com/user/profile/personal_access_tokens/)
* [GitLab access token scopes](https://docs.gitlab.com/security/tokens/access_token_scopes/)
* [GitLab audit events API](https://docs.gitlab.com/api/audit_events/)
* [GitLab REST API authentication](https://docs.gitlab.com/api/rest/authentication/)
* [GitLab action reference](/automations/connectors/gitlab)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.