Use popular Git clients

You can use popular Git clients with WVS instead of using WVS tools. This page shows you how to connect to your WVS project from desktop clients like GitHub, SourceTree, GitKraken, and TortoiseGit.

Process overview

The process for connecting Git clients to your WVS project looks like this:

flowchart LR; id1[Install Git components] --> id2[Create an access token in WVS]; id1[Install Git components] --> id3[Set up an SSH key]; id2 --> id4[Clone your WVS project using a Git client]; id3 --> id4

Prerequisites

You must have a WVS project.

Install Git components

To use third-party Git clients with WVS, you must first install the latest versions of Git and Git LFS:

  1. Download Git for your operating system:
  2. Run the setup file and ensure the following components are selected:
    • Git LFS (Large File Support)
  3. When asked to select an SSH executable, select Use external OpenSSH.

Configure access in WVS

You can authenticate your selected Git client with WVS using either HTTPS or SSH. However, we strongly recommend that you use SSH, because once you clone a WVS project using a Git client, you can interact with that project using only the protocol that you cloned it with.

WVS tools (such as the WVS CLI) require SSH, so if you clone your project using HTTPS, you can’t use WVS tools with the clone. Similarly, if you cloned your project using WVS tools, then you must use SSH to authenticate your Git client.

Create an access token in WVS for HTTPS authentication

If you want to authenticate your Git client using HTTPS (not recommended), you must create a personal access token in WVS. You must use your personal access token as your WVS password when authenticating HTTPS requests.

  1. Go to the Access tokens page in the WVS web console.

  2. Configure the access token as follows:
    • Token name: Choose a descriptive name for the access token.
    • Expires at: Select an expiration date for the access token.
    • Scope: Select api and read_user.
  3. Click Create personal access token.
  4. Copy and save the access token in a safe location. You cannot retrieve the access token again. If you lose your access token, you must create a new one.

Set up an SSH key for SSH authentication

If you want to authenticate your Git client using SSH (recommended), you can generate or use an existing SSH key pair. Add the public key to your WVS account and add the private key to ssh-agent.

Generate an SSH key

Note: To follow these instructions, you must have OpenSSH installed on your workstation. OpenSSH is preinstalled in Windows 10 and later versions. If you’re running an older version of Windows, you can install OpenSSH by following the instructions at Get started with OpenSSH.

If you have an existing public and private SSH key pair that you want to use, you can skip to the next section.

  1. On your local workstation, open PowerShell as an administrator and run:

    PS C:\>ssh-keygen -t ed25519
  2. When prompted to enter a file in which to save the key, enter a path and file name or use the default path and file name shown in the parentheses by pressing Enter:

    Generating public/private ed25519 key pair.
    Enter file in which to save the key (C:\Users\USER_NAME/.ssh/id_ed25519):
  3. When prompted to enter a passphrase, you can either enter a passphrase or leave it blank for no passphrase:

    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in git.
    Your public key has been saved in git.pub.
    The key fingerprint is:
    SHA256:kC3NIo23Y38vKJS45JkeYl5r5+LsKKXd8lE0FZJtz4E USER_NAME@USER
    The key's randomart image is:
    +--[ED25519 256]--+
    |      .ooo       |
    |     o.BE .      |
    |    o X.+o .     |
    |     + *  o      |
    |     .=.S        |
    |  . oooo         |
    | +o++=  ...      |
    |ooo=O+o ....     |
    | .oBB+..   ..    |
    +----[SHA256]-----+

This command creates two files on your workstation:

  • <KEY_NAME>: Stores your private SSH key.
  • <KEY_NAME>.pub: Stores your public SSH key.

Example: If you entered mysshkey as the key name, you’ll see a file named mysshkey that contains your private key and another file named mysshkey.pub that contains your public key.

Add your public SSH key to your WVS account

  1. Locate and open <KEY_NAME>.pub using a text editor and copy all text in the file.
  2. Go to the SSH keys page in the WVS web console.

  3. In the Key text box, paste your public SSH key that you copied from <KEY_NAME>.pub.
  4. Enter an expiration date for the key.
  5. Click Add key.

Add your private SSH key to ssh-agent

  1. On your local workstation, open PowerShell as an administrator:
    1. Open Run by pressing Windows+R.
    2. Enter powershell in the Run text box.
    3. Press Ctrl+Shift+Enter to open PowerShell as an administrator.
    4. In the User account control window that pops up, click Yes.
  2. In PowerShell, enable ssh-agent by running:

    PS C:\>get-service ssh-agent | set-service -startuptype manual
  3. Start ssh-agent by running:

    PS C:\>start-service ssh-agent
  4. Load your SSH key files into ssh-agent by running:

    PS C:\>ssh-add C:\path\to\key\file

Example:

PS C:\> ssh-add c:\users\USER_NAME\.ssh\id_ed25519
Identity added: C:\Users\USER_NAME\.ssh\id_ed25519 (USER_NAME@USER)

Clone your WVS project using a Git client

Once you have your personal access token or SSH key set up, you can use a Git client to clone your WVS project. This section gives you specific step by step instructions on how to clone your project using the most popular clients, but the general process should be similar for all Git clients:

  • Clone your WVS project using your project’s HTTPS or SSH URL.
  • Select a location on your workstation to clone your project to.
  • If you’re authenticating with SSH, you may need to select OpenSSH as your SSH client or select the option to use a local SSH agent. These configurations are usually made in a settings or preferences page.
  • If you’re authenticating with HTTPS, when asked to provide credentials, use your WVS username (not your email address) for the username and use your WVS private access token as the password.

Select a tab for detailed instructions:

Next steps

  • Learn how to automate with Flows.