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

# GitLab

> Configure GitLab as a source control provider for your Ona environments.

Source control integrations can be configured for both [Self-Hosted Runners](/ona/runners/aws/overview) and [Ona Cloud](/ona/runners/ona-cloud). You can set up a GitLab integration during runner creation or in the runner settings. Self-hosted GitLab instances are supported by changing the Host during setup.

## Configuring GitLab Access

If GitLab is already set up on your runner, skip to [Authorizing GitLab Access](#authorizing-gitlab-access).

### Self-Hosted Runners

For self-hosted runners (like AWS), GitLab integration is configured during runner creation or in the runner settings.

There are two ways to integrate with GitLab. Both can be used simultaneously:

1. **OAuth App (Recommended):** Using an OAuth app allows users to sign in more quickly. You'll need to set up an OAuth app within Ona.
2. **Personal Access Token (PAT):** Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.

#### Using OAuth

1. Go to **Settings → Runners** and select the runner you want to configure.
2. In the **Configure repository access** section, click **Select** next to **GitLab**. If other providers are already configured, click **Add a new provider** first.
3. Toggle **Enable OAuth**.
4. Follow the instructions in [GitLab's docs](https://docs.gitlab.com/ee/integration/oauth_provider.html) to create an OAuth app.
   * The app name can be any name you like
   * You can get the callback URL from the configuration dialog
   * Select the required scopes:
     * *api* so that the context URL can be parsed
     * *read\_repository* so that your environment can clone the repository
     * *read\_user* so that the git author name and email can be set in the environment
5. Enter the **Client ID** and **Client Secret** from the OAuth app. The client secret is encrypted with the runner's public key, so only the runner can read it.
6. Click **Save & Test**.

#### Using Personal Access Tokens (PATs)

1. Go to **Settings → Runners** and select the runner you want to configure.
2. In the **Configure repository access** section, click **Select** next to **GitLab**. If other providers are already configured, click **Add a new provider** first.
3. Toggle **Enable Personal Access Token**.
4. Click **Save**.

### Ona Cloud

Ona Cloud provides built-in GitLab integration with no configuration required:

* **gitlab.com** is supported by default using Ona's managed OAuth application
* **No OAuth app setup needed** - Ona manages the OAuth application for you
* **Automatic authentication** - Users can authenticate with their GitLab accounts immediately

For custom GitLab instances or advanced repository access configurations, consider [upgrading to Enterprise](/ona/runners/ona-cloud#upgrading-to-enterprise) with self-hosted runners.

## Authorizing GitLab Access

### Using OAuth

1. When creating your first environment, you will be asked to authorize the new application. To use OAuth press the *Connect* button. A new window will open that directs you to GitLab to authorize the OAuth app. The requested scopes are *api*, *read\_repository* and *read\_user*.

   * The *api* scope is required so that the context url can be parsed
   * The *read\_repository* scope is required so that your environment can clone the repository
   * The *read\_user scope* is required so that the git author name and git author email can be set in the environment

2. After you have authorized, you can close the window. After a few seconds you should get a confirmation that GitLab is now connected.

### Using Personal Access Tokens (PATs)

1. When creating your first environment, you will be asked to authorize the new application. Select *Provide a Personal Access Token*.

   * Click the link provided on the screen to access the configuration dialog for creating a GitLab token.
   * The name of the token and all required scopes are pre-set.
   * By default, the token is valid for 30 days, but you can change the duration if needed.

2. After creating the token, return to the dialog and paste the token.

3. The environment will now be created using the provided token.

## Plan availability

| Plan       | GitLab.com (SaaS) | Self-hosted GitLab      |
| ---------- | ----------------- | ----------------------- |
| Core       | ✓                 | ✗                       |
| Enterprise | ✓                 | ✓ (self-hosted runners) |

GitLab login authentication on the Ona login page is currently in development. In the meantime, sign up with GitHub or Google, then add GitLab at [Settings > Git Authentications](https://app.ona.com/settings/git-authentications).