GitHub Version Control

This document guides you in configuring your GitHub repository with your Insites Instance.

Prerequisites

To understand this tutorial, you need to be familiar with Insites Instances, the concept of Version Control, and GitHub.

• Instances
• Version Control Layer (VCL) Introduction
• Git Repository

Tasks

Configuring your GitHub repository to work with your Insites Instance involves the following tasks:

• Task 1: Retrieve your Insites CLI token
• Task 2: Generate SSH keys for your Git repository
• Task 3: Configure GitHub on your Instance
• Task 4: Configure a user on your Instance
• Task 5: Configure your GitHub repository

The next sections discuss each step in detail.

Task 1: Retrieve your Insites CLI token

To retrieve your Insites CLI token, open the .insites file of your Instance's environment on your local machine. Set the token aside by copying it into your text editor of choice.

Task 2: Generate or retrieve the SSH keys for your Git repository

This section describes how you can generate or retrieve the SSH keys of your Git repository. It includes the following topics:

• Generating SSH keys
• Retrieving a Git repository's SSH key

Generating SSH keys

Follow the steps in GitHub's documentation: Generating a new SSH key and adding it to the ssh-agent. As an overview, the documentation discusses the following steps:

1. Generating a new SSH key.
2. Adding your SSH key to the ssh-agent.

After executing the first step, you are prompted for a passphrase to add an extra layer of security. The second step adds your key to the SSH agent allowing the agent to manage your keys so that you do not have to enter a passphrase every time you want to use the key.

Retrieving a Git repository's SSH key

It is recommended that you check your local machine for existing SSH keys before generating new ones. Follow the steps in Github's documentation: Checking for existing SSH keys. As an overview, the document discusses the following steps:

1. Open Git Bash.
2. Enter ls -al ~/.ssh to see if existing SSH keys are present.
3. Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub include the following.
   • id_rsa.pub
   • id_ecdsa.pub
   • id_ed25519.pub
4. Either generate a new SSH key or upload an existing key.
• If you don't have a supported public and private key pair, or don't want to use the available ones, generate a new SSH key.
• If you see an existing public and private key pair listed (for example, id_rsa.pub and id_rsa) that you would like to use to connect to GitHub, you can add the key to the ssh-agent.

Task 3: Configure GitHub on your Instance

You are now ready to configure GitHub on your Instance! Follow the steps below to proceed:

1. Select Settings from the main menu.
2. Select Integrations.
3. Select Version Control.
--------------------------------------------------------------------------------------------------------------------
4. Click CONFIGURE REPOSITORY. This action takes you to a form you can use to input your repository details.
--------------------------------------------------------------------------------------------------------------------
5. Enable version control using the 'Enable Version Control' toggle on the form.
6. Fill out the 'SSH Repository URL' field with the SSH URL value of your GitHub repository.
--------------------------------------------------------------------------------------------------------------------
7. Fill out the 'SSH Key ID' field with the value of the Insites CLI token you retrieved from Task #1.
--------------------------------------------------------------------------------------------------------------------
8. Select SAVE.

--------------------------------------------------------------------------------------------------------------------

Task 4: Configure a user on your Instance

To add an authorized user:

1. Navigate to Settings from the main menu.
2. Select Version Control.
3. Press the ADD USER button. This action takes you to a form that you can use to fill out with a user's details.
4. Fill out the form with the correct details and press AUTHORIZE USER.

--------------------------------------------------------------------------------------------------------------------

Task 5: Configure your GitHub repository

This section includes the following topics:

• Install the Insites CLI token
• Configure a user

Install the Insites CLI token

To install the Insites CLI token:

1. Install the Insites CLI Tool by running the command sudo npm install -g @insites/insites-cli in your terminal.
2. Login to the Insites Console.
3. Navigate to the Instance to which you want to install the Insites CLI token.
4. Navigate to the 'CLI Commands' tab.
5. Copy the snippet under 'Create Environment.'
6. Open a terminal then paste the snippet. Then, hit 'Enter.'
7. Input your Insites password.
8. To view your Insites-CLI token, open the '.insites' file on your local machine.

Configure a user

To configure a user:

1. Log into GitHub and ensure that your email address matches you user account in Insites.
2. Create SSH keys without a passphrase by following the GitHub documentation

   Your terminal should look something like this
   Note: You may need to show hidden files on your machine to see your key files

3. In your GitHub account, create a new SSH key. You can use any 'title' you wish, and paste the SSH public key you created in step 2.
4. Navigate to Integrations from the main menu of your Insites Instance.
5. Select Version Control.
-------------------------------------------------------------------------------------------------------------------- MISSING STEPS; NEED SCREENSHOTS --------------------------------------------------------------------------------------------------------------------

Note: Version Control is also available for use on team accounts. Please make sure that the user has 'write' or above priviliges.

Alternate ways to view your SSH keys on your machine

To get your SSH public key, type on your terminal cd ~/.ssh and then type open [generated RSA file name].pub

Example: open id_ed25519.pub

To get your SSH private key, type on your terminal cd ~/.ssh and then type open [generated RSA file name]

Example open id_ed25519