Version control
Learn how to use version control in your tracks. Version control helps you streamline development processes, enable faster iteration and delivery of tracks.
This feature is currently in beta and feedback is highly appreciated.
To have the feature enabled for your organization, reach out to customer success, or reach out in either your organization channel on the Instruqt slack workspace or any of the support channels.
Overview
The version control feature allows you to collaborate in real-time across the UI and code workflows with no overwriting and a history of auditing any changes.
Collaborate with confidence
Multiple team members can work on the same content at the same time with no risk of overwriting each other’s changes. If there are conflicting changes made by multiple users, they can be compared, resolved and merged directly in the UI or using git from the command line.
Keep track of changes
All changes made to content are stored, and functions as an audit log showing who changed what, when, and why the changes were made. The changes include the creation and deletion of files as well as edits to their contents.
Having the complete history and being able to annotate each change with the date, an author and a message describing the purpose and intent of the change, enables going back to previous versions to help in root cause analysis for bugs. This capability is crucial when needing to fix problems and being able to compare changes with earlier versions of the content.
Integrate with existing workflows
For content creators that are already using version control systems such as GitHub, the new integration allows you to connect your GitHub organization directly without the need for GitHub actions and the Instruqt CLI to push your content. This allows you to use your standard git workflow best practices already adopted by your organization.
Limitations
In the current beta implementation there are a few limitations to consider:
Currently, a single track per repository is supported. This means that mono-repositories are currently not supported.
Currently, only a single main branch is supported per repository. This can be either
mainormaster.Currently, you can’t play a track if you have unpublished changes for it. If the track is under version control and changes were made but haven't been published yet (the blue bar is on top of the page), then the track can't be played or previewed. Related buttons will be disabled. To play the track you need to either publish the changes or discard them, and the play buttons will be available.
Version Control currently only integrates with GitHub.
Currently, you can only connect a track to an empty repository on GitHub.
Instruqt CLI pushes are not recorded in version control. This can lead to changes from the CLI being either committed to version control at a later time when a new change through the UI is made, or overwritten by an incoming change from GitHub. It is therefore recommended to not use the CLI to push changes in combination with version control.
Virtual Browser UI checks are currently not supported. The creation process of UI checks (available if a virtual browser host exists) requires playing the track that is disabled while unpublished changes exist. UI checks could be deleted through the checks widget on the dashboard and these changes will be under version control. For UI checks creation or modification unsaved changes should be published or discarded first.
Virtual Browser check scripts are still created as normal scripts so they will show as part of a subsequent commit. When creating, editing or deleting Virtual Browser scripts they will still be versioned but they will be added on a subsequent commit after the scripts have been added.
Custom Resources are currently not supported. If the track is under version control but there aren't any unpublished changes, custom resources can be modified, and these changes will be saved immediately, without the need to publish.
If there are unpublished version-controlled changes (the blue bar on top of the page is visible), Custom Resources can't be changed and will be disabled until the other changes are published (by clicking the “Publish” button on the blue bar) or discarded. After that, modifying Custom Resources will be enabled again.
The ID fields might show as part of a subsequent commit. When creating certain entities through the UI such as challenges, sandboxes, track scripts, challenge notes, tabs, etc. temporary IDs are created for these entities and these will be the ID they are initially committed with. This means that the first subsequent commit of those entities might change the value of the ID without it being explicitly changed by the content creator.
Enabling Version Control
Version control is currently in Beta. To have the feature enabled for your organization reach out in either your organization channel on the instruqt slack workspace or any of the support channels.
Enabling Version Control for a track
Once the feature is enabled for your organization you can choose to turn on version control for each track individually. Enabling version control for a track will change the authoring experience of that track for all content creators.
To enable version control, toggle it on in the “Version control” widget, which is visible on the track dashboard.
The moment Version Control is turned on for a track there will be an initial commit containing all the changes made to the track up until that point. The Version Control widget shows the latest change, when it was made, and a commit message that provides additional context about the change. All subsequent changes will be stored individually in version control and visible in the Version Control widget.
Viewing change history
You can view the change history of a track by clicking the “Commits” button on the Version Control widget, or by clicking on the “Created: 28 minutes ago” in the top left of the track dashboard.
The change history contains a list of all changes made to a track. Each entry describes when the change was made, who made the change and the commit message that describes the change. For convenience there is also the git commit hash that can be used to inspect the commit on the command line.
All changes have a detail page that can be accessed by clicking the message for the specific change. The details page shows the contents of the configuration files that were altered in the change. The syntax of these configuration files is the same as used by the instruqt CLI.
Making changes
To start making changes to a track, you can make any change as usual. The main difference is that changes are not directly live, but instead are collected before being published together.
When you make your first change to a track, a blue bar will appear at the top of your track showing that you are currently editing the track and that you have unsaved changes.
In this state, changes won't be permanently saved until they are published. You can keep making changes until you are ready to publish them.
Publishing changes
To publish your changes, and make them available to end-users, click the “Publish” button in the blue Version Control bar at the top of the track screen.
You are then shown a publish dialog, where you can provide a summary of the changes and any additional context that will help other content creators understand what has changed and why these changes were made.
After clicking “Publish”, the changes to the track will be saved and the changes will be reflected in the change history.
How to deal with conflicts
If someone else has published changes to the same track while you were making your changes, there might be conflicting changes. In this case the publish dialog will notify you that there are conflicting changes and that they need to be resolved before being able to publish your changes.
You can provide a summary of your changes and any additional context that will help other content creators understand what has changed and why these changes were made. These messages will be used after the conflicts have been resolved.
When clicking “Resolve conflicts” you are taken to the conflict resolution screen.
This screen shows all configuration files that contain conflicting values, and provides a way to resolve these conflicts by accepting “your changes”, or the “incoming changes” made by others.
If there is a need for more complex conflict resolution, where a combination of the values from both changes is the desired outcome, instead of selecting one of the changes it is possible to change the contents of the files directly in the file editor.
After all conflicts in a file are resolved, click the “Mark as resolved” button for the file to update the “Resolved” counter. Once all conflicts in all configuration files are resolved, the “Publish” button will be enabled.
Clicking “Publish” will save the track with all the changes you have made, including the changes that have been made during the conflict resolution process. The changes summary and additional context that you provided earlier during the publish confirmation will be used to publish the changes.
If any new conflicting changes have been introduced to the track while you were resolving the previous conflicts, you get a dialog prompting you about these new conflicts and asking you to resolve them as before.
Discarding changes
After making any changes, you can choose to discard the changes by clicking “Discard changes” in the blue Version Control bar.
After clicking “Discard changes” you will be prompted to confirm your choice. Doing so will cause all changes that you have made to be lost.
Integrating Version Control with GitHub
Even though Version Control can be used without integrating with a remote Version Control System such as GitHub, there are several benefits that come with using a code-driven workflow.
Possibility to automate of repetitive tasks
Have an off-site backup of your content
Integrate with existing workflows and systems within your organization
Use pullrequests to review changes before they are commited
Increase consistency and reliability of content
To enable the GitHub 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.
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.
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.
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.
Connecting a track to a GitHub repository
To connect a track to a repository on GitHub, go to the track dashboard of the track and ensure that Version Control has been enabled for the track.
In the Version Control widget on the right of the track dashboard, below the latest committed change to the track, click the button “Connect to a remote repository”.
The available repositories of the GitHub organizations that are connected will be listed. Search for the repository you want to connect to the track.
Select the desired repository (the repository must be an empty repository outside of the standard initialized files on GitHub), then click “Connect to repository”.
The track is now correctly connected to the remote repository on GitHub and the Version Control widget will show the name of the connected repository.
Any changes made to the track or the repository will automatically be synched to the other side.
Viewing incoming events from GitHub
On the Version Control widget of each track that is connected to a remote repository, there is a link to view webhook events for that track. This page will show all incoming webhook events from GitHub.
To see more details about a specific event, click it.
Last updated
