# Self-Hosted GitLab

### BetterBugs Integration with Your Self-Hosted GitLab Instance

You can integrate BetterBugs.io with your self-hosted instance on GitLab. 

Whenever you face an issue in your app, you can instantly capture it using the BetterBugs extension and share it with your GitLab self-hosted instance as an issue.

With every issue raised (created as bug reports using BetterBugs) in your GitLab project, you get:

* The visual evidence captured as a screenshot, screen recording, or a 2-minute Rewind video session
* Issue description (added manually or AI-generated by the reporter)
* Device and environment info when the issue occurred.
* Console logs, network requests, and any other logs.
* Page navigation steps
* Metadata (Custom)
* App local and session storage

Your engineers get all this info as a bug report packed with visual evidence and technical details for debugging. You can access the complete bug report with the unique report link included within the GitLab task created as an issue on your self-hosted project.

### What Do You Need for the Setup and How it Works?

{% hint style="info" %}
Here’s what you need to do for integrating your self hosted project:

1. Set up a new OAuth application in GitLab 
2. Use the application (**Application ID** + **Secret**) credentials to integrate BetterBugs.io.

We've covered the steps for it. 
{% endhint %}

### How to Set Up a New OAuth Application in GitLab (for Self-Hosted instance): Step-by-Step

{% stepper %}
{% step %}

#### Login to GitLab

Login to your GitLab self hosted instance.
{% endstep %}

{% step %}

#### Create a New Application

Create a new application in GitLab with the following steps:

1. Click on your **Profile picture** in the top from the navigation pane.
2. Navigate to **Preferences** > **Applications** > **Add new application**
   {% endstep %}

{% step %}

#### Add Name, Redirect URI, and Select Scopes

Add details for the app:

* **Name** — Provide a unique name for your application, (e.g., BetterBugs Test App)
* **Redirect URI** — Here, add “`https://app.betterbugs.io/connect/gitlab`” as the Redirect URI. (*Please use this exact address for any new app(s) you’d want to connect with BetterBugs.)*
* **Confidential** — It should be ✅auto-checked by default.
* **Scopes** — Next, check ✅ only the “`api`” option in scopes. No other options are required.
  {% endstep %}

{% step %}

#### Save

Hit the “**Save application**” button from below to save. 
{% endstep %}

{% step %}

#### Copy the Newly Generated Application Credentials and Hit Continue

Copy your application credentials and keep them handy. You’ll need these to integrate with Betterbugs.

* **Application  ID**
* **Secret**

Now, hit “**Continue**” and you’re all set.
{% endstep %}
{% endstepper %}

### How to Integrate BetterBugs Project with GitLab (for Self-Hosted Instances): Step-by-Step

{% hint style="warning" %}
**PREREQUISITES for BetterBugs.io + GitLab Self-Hosted Integration**

* GitLab **Application ID** and **Secret** (as generated using the above steps)
* Your **GitLab Base URL** (self-hosted)
  {% endhint %}

{% hint style="info" %}
Here, we've covered the steps to integrate a single BetterBugs project (within your BetterBugs Workspace) with GitLab. You can also integrate the complete BetterBugs Workspace in one go (that includes all the projects within your Workspace) to GitLab or any other project tool. [**Check out the steps for Workspace Integration**](/dashboard/workspace-settings/integrations/workspace-integration.md)**.**
{% endhint %}

{% stepper %}
{% step %}

#### Open Workspace Settings > Integrations

Click on BetterBugs Workspace name at the top left side of app screen. Now, click the **gear icon** to open **Workspace Settings** > **Integrations**.
{% endstep %}

{% step %}

#### Search GitLab

In the **Integrations** tab, search for **GitLab** and click to open the **GitLab** card.
{% endstep %}

{% step %}

#### Turn off workspace-wide integration

Toggle off the "**All Projects**" option and hit "**Continue**". You should see the "**Manage per project**" option now.

{% hint style="info" %}
By default, its turned on for workspace level integration. For project-wise integration, you need to disable "**All Projects**".
{% endhint %}
{% endstep %}

{% step %}

#### Select a BetterBugs project to integrate and hit "Connect"

Select a project from the projects name list (that's within your Workspace). From the "**Actions**" column, hit "**Connect**" for that project.
{% endstep %}

{% step %}

#### Select GitLab Version for Integration: Self-hosted Version 

You've two versions for it:

* **Cloud Version** -> Enables you to [connect BetterBugs with gitlab.com with OAuth](/product-features/integrations/gitlab.md).
* **Self-hosted** -> Enables you to connect your self hosted GitLab project with your Personal Access Token.

Select the "**Self-hosted**" Version of GitLab. 
{% endstep %}

{% step %}

#### Enter GitLab application credentials

Enter details for the GitLab application + your GitLab Base URL:

* **Client ID\*** — Application ID
* **Client Secret\*** — Secret
* **Base URL** — GitLab Base URL

{% hint style="warning" %}
**IMPORTANT**

Make sure your **GitLab Base URL** (used during integration) **does not end with a trailing slash**.

**For example**: ✔️ <https://gitlab.example.com>

&#x20;                        ❌ <https://gitlab.example.com/>
{% endhint %}
{% endstep %}

{% step %}

#### **Authorize BetterBugs.io for GitLab**

Authorize BetterBugs.io for your GitLab account.

{% hint style="warning" %}
**IMPORTANT NOTE**&#x20;

If you're on a **free plan**, Steps 6 and 7 are **NOT REQUIRED**. **You can just SKIP** to "[*How to Raise an Issue on GitLab using BetterBugs*](/product-features/integrations/gitlab.md)" section.

**FOR PAID PLANS (Teams and Enterprise)**

Steps 6 and 7 enables you to explicitly choose between:

* **Manual Issue Creation (Default)**: This means for sharing a bug report to GitLab, you'd need to manually populate fields for your GitLab Repo. (**Project**, **Assignees**, **Labels**, and others). Its a **FREE FEATURE**.
* **Automatic Issue Creation:** This means for sharing a bug report to GitLab Repo, you can configure BetterBugs to auto-populate fields for GitLab (**Project**, **Assignees**, **Labels**, and others). Its a **PAID FEATURE**.
  {% endhint %}
  {% endstep %}

{% step %}

#### Optional: Choose your preferred method for creating tickets: Manually or Automatically

From the "**Forward Bug Reports**" dropdown, select your preferred method for creating tickets in your project tool:

* **Manually**: Enables you to **raise issues manually**. *Here, we've selected the manual method to showcase project integration steps.*
* **Automatically**: Enables you to [**raise issues with automation**](/dashboard/workspace-settings/integrations/project-integration/project-automation.md).
  {% endstep %}

{% step %}

#### Optional: Select "Manually" and Connect

Finally, select "**Manually**" from the "**Forward Bug Reports**" dropdown and hit "**Connect**".
{% endstep %}
{% endstepper %}

Okay! You're good to go with the Project level integration for GitLab Self-hosted version. Now, you can create detailed reports and share them as GitLab issues directly from your browser with a few clicks.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.betterbugs.io/product-features/integrations/gitlab/self-hosted-gitlab.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.