GitHub Version Control

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

Prerequisites

To understand this tutorial, it is required that you possess a certain level of familiarity with Instances on Insites, the concept of Version Control, and a particular example of Version Control Layer software known as GitHub.

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

Steps

Configuring your GitHub repository to work with your Insites Instance can be summarised with the following steps:

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

The next sections discuss each step in detail.

Step 1: Retrieve your pOS CLI token

To retrieve your pOS CLI token, open the .pos file of the environment of your Instance on your local machine. Set the token aside by copying it onto your text editor of choice.

Step 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.

Generating SSH keys

Follow the steps in GitHub's documentation: Generating a new SSH key and adding it to the ssh-agent. In summary, the documentation will lead you through the following steps:

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

After executing the first step, you will be prompted for a passphrase to add an extra layer of security. The second step adds your key to the SSH agent which allows the SSH 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

Generally, it is good practice to 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 will lead you to perform 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 are one of 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 wish to use any that are available, 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.

Step 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. Choose Version Control.
3. Click CONFIGURE REPOSITORY. This action takes you to a form you can use to input your repository details.
4. Toggle the switch on the form to enable version control.
5. Fill out the 'Repository SSH URL' field with the SSH URL value of your GitHub repository.
6. Fill out the 'POS CLI Token' field with the value of the pOS CLI token you retrieved from Step #1.
7. Choose SAVE.

Step 4: Configure a user

To add an authorised 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 AUTHORISE USER.

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

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

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

Configuring your GitHub repository

1. pOS CLI Token

1 - Install the PlatformOS CLI Tool by running the command sudo npm install -g @platformos/pos-cli in your terminal

2 - Log in to the pOS partner portal

3 - Navigate to your instance and then copy the command to create an environment as shown here

Example: pos-cli env add --email user@insites.io --url https://insites.staging.oregon.platform-os.com staging

4 - Open a Terminal, then paste the command and hit ‘Enter’. It will ask for your pOS Account password for verification. Please enter it.

5 - Upon successfully creating the environment, open the “.pos” file on your local machine, and you will see your pOS-CLI Token.

3. 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 - Within 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 - Log into Insites -> Site Manager -> Version Control -> Configure a User Configure and fill in the fields accordingly then press 'save'.

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