GitHub

Here you'll learn how to integrate the version control feature with GitHub.

Overview

The version control feature can be integrated with GitHub to allow synching both ways, so your changes on GitHub will be seen on Instruqt and changes on the Instruqt platform will be visible on GitHub. This guide explains how to integrate Instruqt with GitHub and how to have a GitHub repository synched with an Instruqt track.

Step 1: Integrate Instruqt with GitHub

After the feature is enabled by expanding the Settings you will now see a version control option.

Settings option

By clicking the Version Control option there you will now see the option to install the Instruqt app on your GitHub account.

GitHub integration

Clicking Install will take you through a GitHub app installation flow. Where you can select your organisation repository.

Organisation selection

After selecting the organisation you will be able to select which repositories Instruqt will be given access to. This is an important setting as it will dictate which repositories you will be able to integrate with a track.

Currently Instruqt is only able to integrate with repositories without an existing track definition, for this reason, all repositories that are integrated with a track need to be empty. Selecting the Only select repositories means the future repositories created for this integration will need to be added to the list of accessible repositories by Instruqt.

GitHub Instruqt repository access

After selecting Install you should be redirected to Instruqt and it should show that GitHub is now installed.

GitHub installed successfully

Step 2: Integrate a track with a repository

After the installation flow is completed it should now be possible to integrate tracks with your enabled GitHub repositories. Now when accessing a track page the Connect to a remote repository button on the Version control widget should now be enabled.

Version control widget

After clicking the button a new drawer should open that lists all the repositories Instruqt has been given access to on the integration flow.

Instruqt only supports connection of repositories without an initial track definition. This is to avoid a conflict scenario between existing track definitions and the definition being pushed by Instruqt.

Repository connection

When a repository is selected and the Connect to repository button is clicked Instruqt pushes the existing integrated track definition to GitHub and synchronises the track and the repository both ways.

Examples of usage of the feature

The repository integrated should now have a track definition pushed by authored by the user corresponding to the email used to sing in to Instruqt and published by Instruqt. This will always be the case when doing changes on Instruqt to a track connected to a remote repository.

Repository updated

It is now possible to also do changes through a normal git flow. Content creators can change tracks in their local machines using they're preferred tools and as long as the changes produce a push to the main branch it will trigger changes on the track in Instruqt.

Changes to a track through a git flow

The change history will show either the user, if that email is registered to Instruqt, or the corresponding email that did the push to the repository that is connected to the track.

Change history updated by the commit from local git

All features mentioned on version control section of manage tracks should be completely supported while integrating with a remote repository.

Limitations

• Instruqt CLI changes can be overwritten by updating the remote repository: The changes made through the Instruqt CLI are not versioned, this means that if a change is done using the Instruqt CLI and after that another change is made using a normal git flow, the changes done via git flow will overwrite the changes done by the CLI.

To avoid losing potential work being done through the Instruqt CLI we recommend when the track is integrated to use a normal git flow to author tracks.