Help us learn about your current experience with the documentation. Take the survey.

Clone or browse repositories

In VS Code, you can clone Git repositories or browse them in read-only mode.

Clone a Git project

GitLab for VS Code extends the Git: Clone command. For GitLab projects, it supports cloning with either HTTPS or Git URLs.

Prerequisites:

  • To return search results from a GitLab instance, you must have added an access token to that GitLab instance.
  • You must be a member of a project for search to return it as a result.

To search for and clone a GitLab project:

  1. Open the Command Palette by pressing:
    • MacOS: Command+Shift+P.
    • Windows: Control+Shift+P.
  2. Run the Git: Clone command.
  3. Select either GitHub or GitLab as a repository source.
  4. Search for and then select a Repository name.
  5. If cloning a GitLab repository, select a cloning method:
    • To clone with Git, select the URL that begins with user@hostname.com.
    • To clone with HTTPS, select the URL that begins with https://. This method uses your access token to clone the repository, fetch commits, and push commits.
  6. Select a local folder to clone the repository into.
  7. Select whether to open the cloned repository, or add it to your current VS Code workspace.

Browse a repository in read-only mode

With this extension, you can browse a GitLab repository in read-only mode without cloning it.

Prerequisites:

To browse a GitLab repository in read-only mode:

  1. Open the Command Palette by pressing:
    • MacOS: Command+Shift+P.
    • Windows: Control+Shift+P.
  2. Run the GitLab: Open Remote Repository command.
  3. Select Open in current window, Open in new window, or Add to workspace.
  4. To add a repository, select Enter gitlab-remote URL, then enter the gitlab-remote:// URL for your desired project.
  5. To view a repository you’ve already added, select Choose a project, then select your desired project from the dropdown list.
  6. In the dropdown list, select the Git branch you want to view, then press Enter to confirm.

To add a gitlab-remote URL to your VS Code workspace file, see Workspace file in the VS Code documentation.

GitLab remote repository URL format requirements

GitLab remote repository URLs require these parameters:

  • instanceUrl: The GitLab instance URL, not including https:// or http://.
    • If the GitLab instance uses a relative URL, include the relative URL in the URL.
    • For example, the URL for the main branch of the project templates/ui on the instance example.com/gitlab is gitlab-remote://example.com/gitlab/<label>?project=templates/ui&ref=main.
  • label: The text Visual Studio Code uses as the name of this workspace folder:
    • It must appear immediately after the instance URL.
    • It can’t contain unescaped URL components, such as / or ?.
    • For an instance installed at the domain root, such as https://gitlab.com, the label must be the first path element.
    • For URLs that refer to the root of a repository, the label must be the last path element.
    • VS Code treats any path elements that appear after the label as a path inside the repository. For example, gitlab-remote://gitlab.com/GitLab/app?project=gitlab-org/gitlab&ref=master refers to the app directory of the gitlab-org/gitlab repository on GitLab.com.
  • projectId: Can be either the numeric ID (like 5261717) or the namespace (gitlab-org/gitlab-vscode-extension) of the project. If your instance uses a reverse proxy, specify projectId with the numeric ID. For more information, see issue 18775.
  • gitReference: The repository branch or commit SHA.

The parameters are then placed together in this order:

gitlab-remote://<instanceUrl>/<label>?project=<projectId>&ref=<gitReference>

For example, the projectId for the main GitLab project is 278964, so the remote URL for the main GitLab project is:

gitlab-remote://gitlab.com/<label>?project=278964&ref=master