Install and set up the GitLab for VS Code extension

To use the GitLab for VS Code extension, install the extension, connect to GitLab, and then configure it as needed.

Install the extension

Choose the installation method that meets your needs:

• For standard VS Code, install from the Visual Studio Marketplace.
• For unofficial VS Code versions, install from Open VSX Registry.
• For secure local development, install in a Visual Studio Code Dev Container.

Install in a Visual Studio Code Dev Container

For added security, set up the extension and use GitLab Duo in a containerized development environment using VS Code Dev Containers.

Prerequisites:

• Docker is installed and running.
• The Visual Studio Code Dev Containers extension is installed in VS Code.

To install the extension in a VS Code Dev Container:

1. Run the Dev Containers: Add Dev Container Configuration Files command from the Command Palette.

2. Add the GitLab extension to the configuration file:

   jsonCopy

   // .devcontainer/devcontainer.json
   {
   "name": "My Project",
   "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
   "customizations": {
      "vscode": {
         "extensions": [
         "GitLab.gitlab-workflow"
         ]
      }
   }
   }
   

3. Run the Dev Containers: Open Folder in Container command to open your project in a VS Code Dev Container. VS Code automatically installs the extension inside the container.

Connect to GitLab

After you install the extension, authenticate and then connect your project to a repository on GitLab.

Authenticate with GitLab

{{< history >}}

• Introduced OAuth authentication for GitLab Self-Managed and GitLab Dedicated in GitLab for VS Code 6.47.0 during the GitLab 18.3 release.

{{< /history >}}

{{< tabs >}}

{{< tab title="GitLab.com" >}}

Prerequisites:

• For authentication using PAT, a personal access token with the api scope.

To authenticate with GitLab:

1. Open the Command Palette:
   • For macOS, press <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
2. Type GitLab: Authenticate and press <kbd>Enter</kbd>.
3. Select your GitLab instance URL from the options or enter one manually.
   • If you enter one manually, in URL to GitLab instance, paste the full URL, including the http:// or https://. Press <kbd>Enter</kbd> to confirm.
4. Select an authentication method, OAuth or PAT.
   • For OAuth, follow the prompts to sign in and authenticate.
   • For PAT, follow the prompts to create a token or enter an existing one to authenticate.

{{< /tab >}}

{{< tab title="GitLab Self-Managed and GitLab Dedicated" >}}

Prerequisites:

• For authentication using OAuth, the application ID for an OAuth application for VS Code.
• For authentication using PAT, a personal access token with the api scope.

To use OAuth, first configure the OAuth application login:

1. Open the Command Palette:
   • For macOS, press <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
2. Type Preferences: Open User Settings and press <kbd>Enter</kbd>.
3. Select Settings > Extensions > GitLab > Authentication.
4. Under OAuth Client IDs, select Add Item.
5. Select Key and enter the GitLab instance URL.
6. Select Value and enter the ID of the OAuth application.

To authenticate with GitLab:

1. Open the Command Palette:
   • For macOS, press <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
2. Type GitLab: Authenticate and press <kbd>Enter</kbd>.
3. Select your GitLab instance URL from the options or enter one manually.
   • If you enter one manually, in URL to GitLab instance, paste the full URL, including the http:// or https://. Press <kbd>Enter</kbd> to confirm.
4. Select an authentication method, OAuth or PAT.
   • For OAuth, follow the prompts to sign in and authenticate.
   • For PAT, follow the prompts to create a token or enter an existing one to authenticate. {{< /tab >}}

{{< /tabs >}}

The extension matches your Git repository remote URL with the GitLab instance URL you specified for your token. If you have multiple accounts or projects, you can choose the one you want to use.

[!note] If your GitLab instance or network uses a custom SSL setup, you can configure the extension to support self-signed certificates. For more information, see using the extension with self-signed certificates.

Connect to your repository

To connect to your GitLab repository from VS Code:

1. In VS Code, on the top menu, select Terminal > New Terminal.

2. Clone your repository: git clone <repository>.

3. Change to the directory where your repository was cloned and check out your branch: git checkout <branch_name>.

4. Ensure your project is selected:

   1. In the left sidebar, select GitLab ({{< icon name="tanuki" >}}).
   2. Select the project name. If you have multiple projects, select the one you want to work with.

5. In the terminal, ensure your repository is configured with a remote: git remote -v. The results should look similar to:

   plaintextCopy

   origin  [email protected]:gitlab-org/gitlab.git (fetch)
   origin  [email protected]:gitlab-org/gitlab.git (push)
   

   If no remote is defined, or you have multiple remotes:

   1. In the left sidebar, select Source Control ({{< icon name="branch" >}}).
   2. On the Source Control label, right-click and select Repositories.
   3. Next to your repository, select the ellipsis ({{< icon name=ellipsis_h >}}), then Remote > Add Remote.
   4. Select Add remote from GitLab.
   5. Choose a remote.

The extension shows information in the VS Code status bar if both:

• Your project has a pipeline for the last commit.
• Your current branch is associated with a merge request.

Configure the extension

To configure settings, go to Settings > Extensions > GitLab.

Configure accounts and projects

After you authenticate and connect to your repository, the extension automatically associates your GitLab account and project based on your Git repository configuration.

Switch accounts

The extension uses one account for each VS Code workspace (window). It automatically selects the account when:

• You authenticate with only one GitLab account in the extension.
• All workspaces in your VS Code window use the same GitLab account, based on the git remote configuration.

If multiple GitLab accounts exist and the extension cannot determine which account to use, it adds Multiple GitLab Accounts ({{< icon name="question-o" >}}) to the status bar. To select a GitLab account, select the status bar item and follow the prompts.

Alternatively, you can use the Command Palette:

1. Open the Command Palette:
   • For macOS, press <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
2. Run the command GitLab: Select Account for this Workspace.
3. Select an account from the list.

Select a project

The extension uses your Git repository remote to determine which GitLab project to associate with your workspace.

When your Git repository has multiple remotes that point to different GitLab projects, the extension cannot determine which one to use. For example:

• origin: [email protected]:gitlab-org/gitlab-vscode-extension.git
• personal-fork: [email protected]:myusername/gitlab-vscode-extension.git

In these cases, the extension adds a (multiple projects) label to the status bar.

To select a project:

1. In the left sidebar, select GitLab ({{< icon name="tanuki" >}}).
2. Expand Issues and merge requests.
3. Select the line containing (multiple projects, click to select).
4. Select a project from the list.

The Issues and merge requests list updates with your selected project's information.

Change the project

To change your project selection:

1. In the left sidebar, select GitLab ({{< icon name="tanuki" >}}).
2. Expand Issues and merge requests.
3. Select the project.
4. Next to the project name, select Clear Selected Project ({{< icon name="close-xs" >}}).

Configure GitLab Duo

GitLab Duo features are enabled by default in VS Code when you meet the prerequisites:

• For agentic features, you meet the prerequisites for GitLab Duo Agent Platform.
• You have GitLab Duo turned on.
• For flows, you have foundational flows turned on.
• For agents, you have foundational agents turned on and custom agents enabled, as needed.
• You have a default GitLab Duo namespace set or have a project open that has GitLab Duo access.
• For GitLab Duo Code Suggestions, you meet the additional prerequisites.

Turn off GitLab Duo

To turn off GitLab Duo features in VS Code:

1. In VS Code, open the Settings editor:
   • For macOS, press <kbd>Command</kbd>+<kbd>,</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>,</kbd>.
2. Select Extensions > GitLab > GitLab Duo.
3. Find the feature you want to turn off and clear the checkbox.

Configure telemetry

GitLab for VS Code uses the telemetry settings in Visual Studio Code to send usage and error information to GitLab. To turn on or customize telemetry in Visual Studio Code:

1. In VS Code, open the Settings editor:
   • For macOS, press <kbd>Command</kbd>+<kbd>,</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>,</kbd>.
2. Select Application > Telemetry.
3. For Telemetry Level, select the data you want to share:
   • all: Sends usage data, general error telemetry, and crash reports.
   • error: Sends general error telemetry, and crash reports.
   • crash: Sends OS-level crash reports.
   • off: Disables all telemetry data in Visual Studio Code.
4. Save your changes.