Use popular Git clients

This page shows you how to configure popular Git clients, such as GitHub, SourceTree, GitKraken, and TortoiseGit, to work with WVS. If you haven’t used Git clients before or you want to more simplified workflow experience, use WVS Desktop Client instead.

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. If you’re just getting started on WVS, you can follow the instructions in the Fork and clone the “Hello World” project tutorial to fork a demo 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:

Get the latest version of GitHub Desktop.

  1. Go to your WVS project’s Version control > Files page.
  2. Click Clone and copy your WVS project’s URL based on the protocol that you want to authenticate with.
  3. Go to GitHub Desktop and select File > Clone repository….
  4. In the popup window that opens, select the URL tab and configure as follows:
    • Repository URL or GitHub username and repository: Paste your WVS project’s URL that you copied.
    • Local path: Enter the location on your workstation to clone your project to.
  5. Click Clone.
  6. Optional: If you’re using HTTPS, a popup window appears prompting you to log in. You can log in as follows:
    • Username: Enter your WVS username.
    • Password: Enter your personal access token.

Get the latest version of SourceTree.

  1. Go to your WVS project’s Version control > Files page.
  2. Click Clone and copy your WVS project’s URL based on the protocol that you want to authenticate with.
  3. Open the SourceTree app.
  4. Optional: If using SSH, click Tools > Options > General and for SSH client, select OpenSSH and click Ok.
  5. Click File > Clone / New…, and configure as follows:
    • Source path / URL: HTTPS Clone URL of your WVS project.
    • Destination path: Enter the location on your workstation to clone your project to.
  6. Click Clone.
  7. Optional: If you’re using HTTPS and are prompted to enter credentials, you can log in as follows:
    • Username: Enter your WVS username.
    • Password: Enter your personal access token.

Get the latest version of GitKraken.

  1. Go to your WVS project’s Version control > Files page.
  2. Click Clone and copy your WVS project’s URL based on the protocol that you want to authenticate with.
  3. Open the GitKraken app.
  4. Optional: If using SSH, click Preferences > SSH and select Use local SSH agent.
  5. Select File > Clone repo.
  6. Select Clone with URL and configure as follows:
    • Where to clone to: Enter the location on your workstation to clone your project to.
    • URL: Paste your WVS project’s URL that you copied.
  7. Click Clone repo.
  8. Optional: If you’re using HTTPS and are prompted to enter credentials, you can log in as follows:
    • Username: Enter your WVS username.
    • Password: Enter your personal access token.

Get the latest version of TortoiseGit.

  1. Go to your WVS project’s Version control > Files page.
  2. Click Clone and copy your WVS project’s URL based on the protocol that you want to authenticate with.
  3. On your workstation, right click on any folder and select TortoiseGit > Clone….
  4. In the configuration window that pops up, configure as follows:
    • URL: Paste your WVS project’s URL that you copied.
    • Directory: Enter the location on your workstation to clone your project to.
    • LFS: Selected.
  5. Click Ok.
  6. Optional: If you’re using HTTPS and are prompted to enter credentials, you can log in as follows:
    • Username: Enter your WVS username.
    • Password: Enter your personal access token.

Next steps

  • Learn how to automate common tasks with flows.