Setting up Version Control

Install Git

To manage content on Instruqt we will use Git as version control. Git can be installed on the most common operating systems such as Windows, macOS, and Linux. If you are on macOS and many Linux distributions, Git might already be installed on your system.

To verify if you already have Git installed, open up the terminal application on your system and run the git version command. You should either see which version of the git binary is currently installed, or "command not found". If Git is not installed on your machine, check the specific documentation for either macOS, Windows or Linux to install Git.

Configure Git

The first thing you should do is to configure your identity that Git will use to identify your commits. Lets start by configuring your name, which will give others an easy way to recognize the author of your commits. Execute the following command in a terminal, with "Your Name" replaced by your own name.

git config --global user.name "Your Name"

The other important identifying information needed to create a commit is your email address. This makes it easy to differentiate authors with the same name. In a terminal, execute the following command and replace "[e-mail]" with your own email address. We will use this same email address in a following step, so be sure that this is a valid email address.

git config --global user.email [e-mail]

Create a GitHub account

If you do not have a GitHub account yet, create one with the same email address as configured in the previous step.

Generate an SSH key

In order to authenticate Git with GitHub it will need an SSH key. To generate a new SSH key, open the terminal and execute ssh-keygen -t ed25519 -C "[e-mail]" with the same email address you configured before. This creates a new SSH key, using the provided email as a label to identify it by.

When you're prompted to "Enter a file in which to save the key", you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ALGORITHM with your custom key name.

When prompted to enter a passphrase, type a secure passphrase and press Enter. Please note that the entered passphrase will not be shown, so it might look like nothing is happening. Type the same passphrase again and press Enter to confirm.

> Generating public/private ALGORITHM key pair.
> Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM): [Press enter]
> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

If everything went correct, you should be presented with a representation of your key in ASCII art.

The Key fingerprint is:
SHA256:FHs80yt3r2fehwfoweyufewhfweip [e-mail]
The key's randomart image is:
+--[ED22519 256]--+
|       .++       |
|       .+..     .|
|     . .   . . ..|
|    . .     .E.. |
|     ...S     .  |
|      o+.        |
|     +..o        |
|  o B .o.        |
| . + +..         |
+-----[SHA256]----+

Add an SSH key to your GitHub account

In order for GitHub to recognize that this newly generated SSH key is associated with your account, you need to add the key to your account.

First, copy the SSH public key to your clipboard. In a terminal execute the following command:

pbcopy < ~/.ssh/id_ed25519.pub

Then open up GitHub in the browser, sign in and follow the steps:

1. In the upper-right corner of any page on GitHub, click your profile photo, then click Settings.

2. In the "Access" section of the sidebar, click SSH and GPG keys.

3. Click New SSH key or Add SSH key.

4. In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal laptop, you might call this key "Personal laptop".

5. For the type of key, select authentication.

6. In the "Key" field, paste your public key.

7. Click Add SSH key.

8. If prompted, confirm access to your account on GitHub.

Your SSH key is now added to your GitHub account, and can be used by Git to authenticate itself as you when performing actions.

Setting up the Instruqt GitHub integration

In order to integrate GitHub with Instruqt, you need to set up the integration.

Configure integration

Navigate to the Version Control settings page.

The VCS integrations are listed, with GitHub currently being the only option. Click the "Install" button on the GitHub integration to install the Instruqt GitHub application in your GitHub organization. You will then be redirected to GitHub, where you are taken through the GitHub application installation flow.

Select organization

First you need to select the organization you want to install the application in.

Depending on your settings, the flow might ask you to provide two-factor authentication details to GitHub.

Configure permissions

You are then taken to the application permissions page, where you can review which permissions the application wants to use.

The permissions that the Instruqt GitHub application needs are:

• Read access to metadata (this is the default permissions for an application)

  • read the organization name, etc.

• Read and write access to code

  • This allows the integration to read the contents of a track repository, so it can update the data in the Instruqt platform with any changes made through GitHub.

  • This allows the integration to write changes made in the instruqt UI back to the track repository on GitHub.

You can choose to give the permissions on all repositories in the organization, or to specific repositories only.

Install GitHub application

To complete the installation, click “Install” to confirm your choices and install the application.

You are then taken back to the Version Control settings page, which now shows that the integration was successfully installed.